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THE ST PROGRAMMING MANUAL THAT TEACHES 
BOTH C AND GEM PROGRAMMING TECHNIQUES. 


LEARN TO: 


• Program in C. 

• Perform raster operations. 

• Use VDI graphics primitives. 

• Design and program dialogs. 

• Create custom mouse forms. 

• Handle multiple windows. 

• Call up alert boxes. 

• Write desk accessories. 

• Manipulate file selectors. 

• Program animation. 

• Design and program menu bars. 

• Write a complete GEM application. 

• And much more! 


For nearly four years, readers of ANALOG Computing and ST-Log looked forward to Clayton 
Walnum's monthly "C-manship" column. From the basics of C, through to the creation of 
sophisticated GEM application programs, Clayton Walnum lead his readers, step-by-step, through the 
sometimes exasperating, sometimes exhilarating, always challenging, experience of C programming 
on the Atari ST. 


Now all 31 "C-manship" columns, edited and updated, have been compiled into this book. People 
who followed the original series will be delighted to have all the columns organized into a single 
volume, while those who missed "C-manship" the first time around now have a second chance to 
learn the tricks of the professional ST programmers. 

"Clayton Walnum not only succeeds in teaching the C language, but also explains the intricacies of 
GEM better than I've seen it done anywhere." —David Plotkin 
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INTRODUCTION 

This book was four years in the making. 

Whew! When I read that sentence, I feel like a refugee from the Twilight Zone. Four years! If 
someone back in 1986 had whispered in my ear that I would write a C programming tutorial totaling 
over 80,000 words and including hundreds of K of source code, I would have asked how he had 
escaped from his rubber room. 

But here it is, in black and white: C-manship Complete. Where did all that time go? 

Some History 

I had been working as a full-time employee of A.N.A.L.O.G. 400/800 Corp. (publishers of A.N.A.L.O.G. 
Computing and ST-Log magazines) for less than a year when the editors asked me to write a C 
programming tutorial for the ST. Being a rookie on the staff, and anxious to write as much as 
possible, I swore that they could count on me. Yes, indeed, I'd teach all those new ST owners to make 
their computers perform the most amazing tricks. 

But, I mumbled to myself as I slinked back to my desk, who was going to teach me? 

At that time, GEM and I were not on good terms. GEM was an intimidating beast that leered from 
the pages of poorly written documentation, page after page of obscure text through which I would 
have to muddle if I was to fulfill the challenge that had been laid before me. 

Was I nervous? You bet! Back in those early days, only high-tech wizards knew anything about 
windows and dialog boxes. They locked themselves in dusty little rooms, and, shrouded in the glow 
from their monitors, tapped endlessly at their keyboards, while gulping gallons of Coke and 
munching bushels of Twinkies. They conversed in a secret language. Words like "workstation," 
"tedinfo," "raster," and "touchexit" fell from their lips in a stream of jargon that could bring other 
professional programmers to their knees. 

I was terrified. 

I realized, though, that I had something to offer that none of the high-tech wizards had: a novice's 
viewpoint. As I learned to tame the beast called GEM, I would stumble into all the traps, then learn to 
avoid them, immediately passing on what I had learned to my readers. We would learn together, the 
readers and me. 

So, I set to work. 

Some month's, particularly in the beginning, the job was easy: Take some notes. Write a sample 
program. Compose a tutorial. Hey, this wasn't so bad, after all! But there were months when 
producing a column was tougher than slogging through a room full of week-old jello. The research 
crawled. The programs bombed. I'd stare, perplexed and panicked, at a line of error messages as long 
as the source code for TOS, as my deadline, the demon of the magazine biz, slipped ever closer. 

Nevertheless, I made every deadline. Yes, I know; there were months when "C-manship" was missing 
from ST-Log, but that was always due to situations beyond my control -- having to attend a trade 
show, for example. As my responsibilities grew, as I advanced from programmer to technical editor 
and, eventually, to executive editor, more and more installments of "C-manship" were missed. But 
never once because GEM pinned me to the mat. 

What's the point? If you're willing to apply yourself, you too can learn C and GEM programming. 
That's a promise. If an idiot like me can write this book, then a smart cookie like you can understand 
and apply it. Really. 
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C-Manship, the Book 

By the last issue of ST-Log (December, 1989), 31 installments of "C-manship" had been published. 
Each of those installments is included in this book. 

Some chapters have been edited in order to bring the material up to date. For example, all the 
programs will now compile with either the original Megamax C or with Laser C. In addition, errors (at 
least those of which I was aware) have been corrected. Finally, in the course of editing this book, I 
deleted the reader's letters that started off some of the earlier columns. 

Except for the above changes, each of the "C-manship" columns is presented in this book exactly as it 
was originally published in A.N.A.L.O.G. Computing and ST-Log, and in the same order. Even the 
illustrations have been reproduced (and some extra ones added). 

Because "C-manship" was written as a series of monthly tutorials rather than as a book, you might 
find that the chapters jump erratically from one topic to another, rather than progressing smoothly 
forward in text-book fashion. That's okay. This book is a series of C programming experiments, not a 
C programming reference. 

That's not to say that C-manship Complete can't be used as a reference. It can. By taking advantage 
of the index, you should have little difficulty finding information you need. C-manship Complete, 
however, is not organized as a reference book. (For a C programming reference, I recommend The C 
Programming Language by Kernighan and Ritchie, published by Prentice-Hall. The manual that came 
with your Laser C or Megamax C compiler makes a good GEM and TOS reference.) Even so, each 
chapter builds upon the information covered in previous ones. If you read the chapters in order, 
you'll always be prepared for the current topic. I promise you that, if you start with Chapter 1 and 
read through to Chapter 31, studying the sample programs and doing the experiments, you will get a 
good grasp of both C and GEM programming. 


Some Important Details 

Most of the sample programs in C-manship Complete are compatible with both Megamax C and 
Laser C. If you have a different compiler, you may have to make some changes to the source code to 
get it to run. However, because there are major differences between Megamax C and Laser C, most 
notably the 32K segment restriction with the former, a few of the sample programs will compile only 
with Laser C. 


Further, although most of the sample programs will run fine on either color or monochrome systems, 
a few can be run only on one or the other. 


In summary, all the programs in C-manship Complete are compatible with both Megamax C and 
Laser C, and with color or monochrome systems, with the following exceptions: 

Chapter 10 : Color suggested. 

Chapter 13 : Program 2, color only. 

Chapter 20 : Laser compatible only with header files changes. 

Chapter 26 : Color only. 

Chapters 27-31: Laser C only. 


If your system won't run all the sample programs, don't panic. Even though it's helpful to see 
examples in action, each chapter covers the material completely enough (sometimes even providing 
sample output) that you'll have no difficulty understanding the topic. Whether or not a program will 
run on your system, however, do study the source code carefully. Moreover, if a sample program is 
incompatible with your system, find the problem and correct it. Program debugging is an art that can 
be learned only through application. 
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What about the Disks? 

As you know, C-manship Complete is also available in a disk version. The disks are incredibly 
reasonably priced (only $10 for two single-sided disks), so I would urge anyone buying this book to 
also get the disks. 

But do you really need the disk version? The answer depends on your definition of "need." If you like 
to type — and then debug — a lot of program listings, everything required for every sample program is 
included in these pages. However, some of the program listings, particularly in the chapters on GEM, 
are extremely long. You would save a great deal of time by having the source code on disk. 

Also, in addition to all the sample programs in the book (in source and compiled form), the disk 
version contains the complete MicroCheck ST home checkbook program, portions of which make up 
the final five chapters of this book. The complete documentation and source code for MicroCheck ST 
are also on the disk. In my humble (yeah, right) opinion, MicroCheck ST, which is a commercial- 
quality application, is itself worth much more than a measly ten bucks. 

Bottom line: It's up to you. 

Let's Boogie 

Writing C-manship has been one of the greatest challenges and pleasures of my life. I'm delighted 
that I have had this opportunity to share that challenge with you and thank you for the trust you've 
shown by buying this book. I hope you'll be pleased. 

All set? 

Then hoist the anchor, and let's set sail. 

Clayton Walnum 
August, 1990 
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CHAPTER 1 - SOME BASICS 

When it comes to programming languages for the ST, we have a lot of options, including BASIC (in 
many different "dialects"), LOGO, Pascal, Modula-2, assembly language and C. (There are a few 
others, but they haven't received widespread use.) Each of these languages has its advantages and 
disadvantages. 

LOGO — one of the languages that are packed with the ST — is a good beginner's language, but has 
many limitations and is very slow. On top of that, few people are familiar with it (which makes its 
inclusion with the ST seem strange). 

Another possibility is assembly language. If you happen to be familiar with the Motorola 68000's 
instruction set and have the time, patience and necessary documentation to make your ST perform 
its tricks, go to it! As for the rest of us? Next. 

How about BASIC? This is a popular language for the ST, if for no other reason than it's an old friend. 
But in considering BASIC as a programming environment, one has to ask an important question: why 
are programmers of the 8-bit Atari machines, slowly but surely, abandoning BASIC and moving to 
Action!? Answer: because Action! provides the convenience of a high-level language with the speed 
of assembly language. 

And guess what? There is just such a language available for use on the ST. 

For those who haven't guessed the obvious, this language is C. 

Why C? 

C is a high-level language that's compiled into machine language form. This means programs can be 
developed quickly and easily, but still retain the speed of machine language. 

Also, C encourages the use of structured programming techniques. If that buzzword "structured" 
doesn't mean anything to you now, it will when you've finished learning about C. I promise you that, 
once you get accustomed to structured programming, you won't want to go back to the old 
"spaghetti code" of BASIC. 

Another important characteristic of C is its compactness. There are only about thirty reserved words. 
This yields a language that is easy to learn, yet extremely powerful. 

One of the qualities of C that has made it popular with professional software developers is its 
portability. Programs can be transferred from one machine to another with a minimum of effort. This 
means that, once a software package has been developed, it can be marketed for many machines 
with very little extra expense. 

If none of the above makes an impression, consider that a large quantity of the software that is 
available for the ST was written in C. Does that tell you something? 

C, Wherefore Art Thou? 

I'll assume at this point that you're all hopping up and down, anxious to start your first programming 
experiments with C. Unfortunately, if you go through all that packaging your computer was packed 
in, you'll quickly discover that there's nothing with "C" written on the label. That's right, folks. You're 
going to have to track down a copy on your own. 

There are many C compilers available for your machine, but the most popular ones seem to be 
Megamax C, Mark Williams C and the DRI compiler that comes with the Atari Developer's Kit. For the 
purposes of this book, I've chosen the Megamax compiler (and the new version of the Megamax 
compiler, Laser C). It's fast, fairly easy to use and is an excellent compiler to use for your first forays 
into C programming, due to it's easy to use GEM interface. If you choose to use a compiler other than 
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Megamax or Laser C, you may have to make some slight changes to the programs presented in this 
book in order to get the programs to run properly. 

Underway At Last 

Now that we've gotten all the preliminaries out of the way, let's take a look at the way C programs 
are created. 

C programs are written using a text editor. How sophisticated the editor is will depend upon the C 
package you're using. Since C source code is really nothing more than a text file, you can use many 
different word processing programs. The only restriction is that the text must be saved to disk 
without the extra codes that some word processors automatically add to your files. 

Once the source code has been written, it must be "compiled." How complicated this process is 
depends, once again, on what software you're using. But essentially, during the compilation, the 
source file is read in from the disk and translated into an "object" file. This object file is stored on 
your disk in a form that your computer can understand (machine language). The object file is then 
"linked" with the other object files that may be needed, and the executable file (the runnable 
program) is written to your disk. Sounds easy, right? Good! Let's get on with it. 

A Simple Program 

Get your text editor loaded up and type in the following code exactly as it appears here (Don't type 
the line numbers.): 

1 #include <stdio.h> 

2 main() 

3 { 

4 char ch; 

5 

6 printf ("Press return\n") ; 

7 ch = getchar(); 

8 } 


Now compile and link the program (refer to your compiler's manual for instructions on how to do 
this) and run it. What happened? Bet you made some typing errors! You'll find that the compiler is 
very fussy. If you're used to programming in BASIC, you've been spoiled by getting syntax error 
messages immediately upon entering a new line of code. Life isn't so simple when you're dealing 
with a text editor. It will let you enter any kind of mumbo-jumbo. Your compiler, however, will do a 
lot of whining if it doesn't see exactly what it expects. 

So go back to your text editor (unless you managed to get the program typed right the first time), 
and correct your source code; then try to compile it again. Got it? 

When you run the program, the words "Press return" should be printed on your screen. Pressing 
Return will bring you back to the ST's desktop. Let's take a look at the code and figure out what's 
going on. I'll refer to the program lines by line numbers, even though C does not use line numbers. 
(That's why there are line numbers to the left of the source code lines.) 

Line 1 tells the compiler to look on your disk for a file called "STDIO.H" and insert whatever code it 
contains into your program. This file is supplied with your compiler and contains input/output 
information for your ST. The filename stands for STandarD Input/Output Header, and though not 
every program you write will need it, it's a good idea, until you really know what you're doing, to 
include it - just in case. 
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Line 2 is a function name. C programs are made up of one or more functions, executed in a sequence 
specified by the programmer. Large programs will contain many functions, each doing a small part of 
the total job. Breaking a program up into small portions makes the programmer's job easier and 
results in source code that's more readable. 

A function can be quickly identified by the parentheses which follow its name. In our example, the 
parentheses are empty, but this won't always be the case. Sometimes we may wish to send values to 
a function when we call it. These values are called "arguments," and the variables which will receive 
these values are placed within the parentheses. In our case, there are no arguments being passed, so 
the parentheses remain empty. If you're a bit confused, don't worry about it. We'll get into functions 
in greater detail later on. 

The function main() is not your everyday, garden-variety function. Every C program must contain 
main(), for it's here that program execution begins. 

Line 3 contains nothing but a left brace. It marks the beginning of our function. The body of every 
function must begin with a left brace and end with a right brace. All the program statements that 
make up the function fall in between. 

Line 4 is a declaration statement. It declares a variable of the type character and gives it the name ch. 
Every variable in your C program must be declared before it's used. This allows the compiler to 
allocate the proper type of storage and supplies your computer with the information it needs to 
interpret the data properly. 

The word char is a C keyword, a word that's been set aside for specific use within the language. 
Keywords may never be used for any other purpose, such as function or variable names. Here is a list 
of C keywords: 


auto 

C Keywords 

Extern 

short 

break 

float 

sizeof 

Case 

for 

static 

Char 

goto 

struct 

continue 

if 

switch 

Default 

int 

typedef 

do 

long 

union 

Double 

register 

unsigned 

else 

return 

while 


Notice, in our declaration of ch, the semicolon at the end. All program statements in C must be 
followed by a semicolon. But, wait a minute! What about Lines 1 and 2? They're missing their 
semicolons! Not really. The former is a compiler directive, not a program statement, so it doesn't 
require a semicolon. 

Function names are also excluded from the semicolon rule. 

Line 6 is the equivalent of a print statement in BASIC. See the parentheses following the word 
printfQ? What does this tell you? If you said that it has something to do with a function, you're 
absolutely correct. This line is a function call. The text inside the parentheses is the argument we 
wish sent to the function. 

The astute among you may now be checking the program listing for a function called printf(). Don't 
bother. It's an additional C function that's added to your program when your program is linked. Your 
C compiler provides many "extra" functions like printf(). Though they are not really part of the C 
language, they are functions that are used a lot by programmers and so are supplied for your 
convenience. Also note that printf(), being a function name, isn't a keyword. 

The argument for printfQ is the text you want printed, plus any format control characters you wish to 
include. See the n with the backslash in front of it? This is the escape sequence that moves the cursor 
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to the next line. If we hadn't inserted it in our text, the next line we printed would be on the same 
line as the first. There are five control characters that may be used with printf(). They are: 

\n -- new line 

\r -- carriage return 

\t -- tab 

\b -- backspace 

\f -- form feed 

When the compiler sees the backslash, it knows that it should interpret the next character as a 
control code. (Note that, even though each control appears as two characters on your screen, they're 
stored as a single character in the computer's memory.) What if you want a backslash in your text? 

No problem. There are three escape sequences to let you print characters which may confuse the 
compiler. They are: 

\\ -- backslash 
\" -- quote 
\' -- single quote 

See those parentheses in Line 7? That's right. We're calling another function. The function getcharQ 
accepts a single character from the keyboard and is one of the functions defined in the STDIO.H file. 
Aren't you glad we included it? Here, we're taking the character returned by getcharQ and placing it 
in the variable ch. 

There is, however, one complication with getcharQ that I should mention here. Because the ST's 
keyboard is buffered, getcharQ won't return anything from the console until the return key is 
pressed, and then, of course, the character it gives back to us will be Return. To get a single character 
from the ST's keyboard, we have to have to resort to a call to the ST's operating system. But we'll 
save that discussion for later. 

Something worth noting at this point is the way the expression ch = getcharQ is evaluated. The equal 
sign is an assignment operator and doesn't mean "equal to." C has a separate operator, ==, for the 
equal condition. The expression a = b should be read as "a gets the value of b." Contrast that with the 
statement if a == b, which is read "if a equals b." 

Line 8 is the right brace to mark the end of our function (and our program as well, in this case). The 
program has ended, and control is returned to your ST's operating system. 

Where's the Beef? 

Okay, now let's look at something with a little more meat to it. Type the following code into your text 
editor and compile it. 

#include <stdio.h> 
main() 

{ 

char ch; 

int numl,num2,ans; 

printf( "Enter two numbers: "); 

scanf("%d %d" ,Snuml,&num2); 

ans = numl + num2; 

printf ("\n\n") ; 

printf ("The sum of %d & %d is %d numl,num2,ans); 
printf (" \n\nPress return\n") ; 
ch = getchar(); 
ch = getchar(); 

} 

When you run this one, you'll be prompted to enter two numbers. Enter them one after the other, 
separated by one space (5 10), and then press Return. Presto! Now your computer's doing first grade 
math. Let's see what's going on. 
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Lines 1 through 4 are now old hat. You should be able to figure them out with little difficulty. Line 5, 
though, gives us something new to chew on. Here, we're declaring three variables of the type 
integer, another of C's basic data types. C interprets an integer as any whole number from -32,768 to 
32,767. 

Notice I said whole number. No decimal portions are allowed. 

Why are we restricted to this range? On the ST computer, an integer is stored in two bytes. That 
gives us 16 bits, or a maximum value of 65,535. Unfortunately, all 16 bits aren't used to store the 
value, since the most significant bit (bit 15 counting from left to right and starting with 0) holds the 
number's sign. It's set when the number is negative and cleared when the number is positive. With 
15 bits, the maximum value that can be represented is 32,767. 

If you need to use a larger integer value, you may declare the variable as unsigned int, or the 
abbreviated version, unsigned. This will free up the sign bit and allow any whole positive number up 
to 65,535. If this range is still not satisfactory, use the long int (abbreviated long) data type. This 
increases the length of the variable's storage to four bytes. Now you can work with numbers from 
about negative two billion to positive two billion. That big enough for you? Here are some 
declaration examples: 

unsigned numl, num2; 
long ans; 
float num3; 

You may declare as many variables on one line as you wish, as long as they're all the same type and 
are separated by commas. 

Line 6 is our old friend printf(), only this time we've left off the newline character, so that whatever 
text is printed next will appear on the same line. 

Line 7 introduces you to a new function, scanf(). This is an input function, and, in our case, it is 
looking for two numbers separated by spaces to be input from the keyboard. 

The arguments for scanf() consist of a control string and a list of pointers. The control string may 
consist of white space characters (blanks, tabs, etc.) and conversion specifications. The pointers are 
the addresses where you wish the data to be stored. 

Okay, okay, I'll slow down. First, let's look more closely at the control string. 

The control string is the portion of the function call that appears between the quotes. There are two 
conversion specifications in our example, both of which tell the computer to expect the input of an 
integer. Take note of the syntax. 

The control string is within quotes, just like any other string, and the conversion character d is 
preceded by the percent sign. Each control specification is matched with its corresponding argument. 
In other words, in our example, the first %d is paired with &numl and the second with &num2. The 
ampersand (&) tells the compiler we want the address of numl and num2, not their value. This is 
important. If you leave off the ampersands (and believe me, sooner or later you will), you're 
guaranteed to see those famous ST bombs appear on your screen. For instance, look at this program 
fragment: 

numl = 100; 
num2 = 150; 

scanf ( "%d %d", numl, num2 ); 

When we enter the data into scanf() in this example, the first value will be stored in memory at 
address 100 decimal and the second at address 150 decimal. Ouch! 

A word of warning about scanf(): Many C programmers will not use this function because it assumes 
too much on the part of the person typing in the data and the person who wrote the scanf() routine. 
In other words, if the data that's input to scanf() is not exactly what the function expects to see, you 
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may get unpredictable results. In following chapters, we'll see how to get around scanf() by writing 
our own input routines. 

Getting back to the program, Line 8 is where we do the calculation, which brings us to a short 
discussion of data types. In C there are many different data types, including not only integer and 
floating point, but also long, short, unsigned and character. Some danger lies in the fact that C allows 
you to mix these data types with impunity. When you do, C will do type conversions on the numbers, 
and you may not end up with what you expect. 

In this example, we're adding two integers, numl and num2, and assigning their value to a third 
integer, ans. Although we're not mixing data types, we're still not out of danger. We must be sure 
that the result of our calculation falls within the -32,768 to +32,767 range that we discussed earlier. 

Hmmm. What happens if we try to add 1 to an integer that's already at its maximum value of 32,767? 
Can you guess? You'll end up with a result of -32,768. This is called an "overflow." You get a result of - 
32,768 because the integer wraps around from its highest value back to its lowest. 

What will you end up with if you add 2 to an integer value of 32,767? If you guessed -32,767, you're 
right! 

Be forewarned: C doesn't care about overflows and will not give you an error message. 

Now that we've done our calculation, we have to get the answer out to the user. We do this with our 
old pal printf(). 

Line 9 does nothing more than leave a blank line between the earlier text and the text we'll be 
printing next. 

Line 10 actually prints out the final data. Take a good look at the control string. There are those 
conversion specifications again, only this time we're not accepting values from the keyboard; we're 
printing them to the screen. We put the conversion specification %d wherever we wish to have an 
integer printed in the text. 

Following the control string are the matching arguments for the conversion specifications. Each %d 
pairs with an argument in the same manner as scanf(). You must be sure that the arguments match 
the control string properly, or you'll get unpredictable results. 

There are nine basic conversion specifications you may use. They are: 

%d -- decimal integer 
%f -- floating point 

%e -- floating point, scientific notation 
%c -- single character 
%s -- string 

%g -- use the shorter of %f or %e 
%u -- unsigned decimal integer 
%o -- unsigned octal integer 
%x -- unsigned hex integer 

If some of these confuse you, don't worry about it. We'll get to them in due time. 

Getting back to Line 10, when the text is printed, whatever you entered as the first number (now 
stored in numl) will be substituted for the first %d, the second number (num2) will replace the 
second %d, and the sum (ans) will be printed in place of the last %d. 

Study this use of the printfQ function closely until you understand it. You'll see it a lot, and many 
times it'll be much more complicated. Just remember that none of the conversion specifications are 
printed literally. 

Lines 11,12, and 13 bring us back to familiar territory. But why are we using the getcharQ function 
twice? Remember when you entered those two numbers, then pressed Return? Well, the first 
number was stored in the variable numl and the second in num2, but the Return didn't have any 
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place to go, so it stayed in the keyboard buffer. When we call getcharQ the first time, the Return 
gladly jumps into our character variable ch, and the program goes on its merry way. If we didn't have 
the second getcharQ, the program wouldn't pause for our next input. 

Now spend some time writing a few simple programs using what you've learned. When you feel 
comfortable with the material presented here, move on to the next chapter. 
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CHAPTER 2 - A LOOK AT STRINGS 

In chapter 1, we looked at how a simple C program is constructed. Along the way, we also learned a 
bit about the basic data types and got an introduction to the C functions printfQ, scanf() and 
getcharQ. Now that we've got all that mastered, it's time to learn how to handle strings. We'll also 
take a closer look at the printfQ and scanf() functions. 

Of course, you have a job to do first... namely, typing and compiling the following program: 

#include <stdio.h> 

#define TEXT "Your full name is" 

main () 

{ 

char ch; 

char fname [20], lname [20]; 

printf( "Enter your first name: " ); 
scanf( "%s", fname ); 
printf( "\n\n" ); 

printf ("Hi, %s! Enter your last name: ", fname); 
scanf( "%s", lname ); 
printf( "\n\n" ); 

printf ("%s %s %s.\n\n", TEXT,fname, lname); 
ch = getchar(); 
ch = getchar(); 

} 

Got it? When you run the program, you will be prompted to enter your first name. Type in your 
name, terminating the input with Return. You'll get a personal hello and be asked for your last name. 
When you enter it, the program will print some important information (your name), after which it'll 
wait for you to press Return to end the program. A program run will look something like this: 

Enter your first name: Clay 

Hi, Clay! Enter your last name: Walnum 

Your full name is Clay Walnum. 

A Look at the Program 

Line 1 instructs the compiler to add the contents of the STDIO.H file to our program. 

Line 2 introduces us to the #define statement. The format of this statement is the word #define, 
followed by a symbolic name and the value we wish placed in the name. In our example, the 
symbolic name TEXT will contain the string constant Your full name is. 

Since C doesn't provide the programmer with a special data type for strings, they are stored as an 
array of characters. The last character in this array will be the null character (zero). We don't have to 
worry about supplying the null character, though. It's added automatically. Here's a graphic 
representation of how the string constant TEXT looks in memory: 


Y 

0 

U 

R 


N 

A 

M 

E 


I 

S 

\0 


Your C compiler contains a program known as the "preprocessor." When you compile a program, the 
preprocessor searches for any occurrence of items that were defined by the #define statement. 
Wherever it finds a match, it replaces the symbolic name with the value the name contains. In other 
words, in our program, every place the word TEXT appears, the string Your full name is will be 
substituted. Notice that there's no semi-colon at the end of a #define statement. It's a compiler 
directive and not subject to the semi-colon rule. 
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Here are a few other examples of the #define: 

#define ZERO 0 
#define PI 3.14159 
#define PLUS + 

Why do we bother with the #define statement? Why not just use a regular variable? After all, aren't 
the statements pi = 3.14 and #define PI 3.14 really equivalent? 

No! The difference has to do with the preprocessor we discussed earlier. By using #define, your 
program will actually run a bit faster than if you used a variable name. The reason is that each time a 
variable is encountered in the program; its storage location must be "peeked" to get its value. This is 
called "run-time substitution." With #define, the substitution is accomplished during compilation 
(compile-time substitution), so that when the program is run, the values are already in place. 

You're probably beginning to realize just how powerful the #define statement is. The following 
program listing shows an extreme use of #define. The program hardly looks like C anymore. 

#include <stdio.h> 

#define START { 

#define STOP } 

#define INPUT scanf 
#define OUTPUT printf 
#define TIMES * 

#define EQUALS = 

#define SQUARES main)) 

#define WAIT ch=getchar() 

int isconio; 


SQUARES 

START 

int num,ans; 
char ch; 

_isconio = 1; 

OUTPUT ( "Enter a number: " ); 

INPUT ( "%d" , Snum ); 

OUTPUT ( "\n\n" ); 

ans EQUALS num TIMES num; 

OUTPUT ("The square of %d is %d.", num, ans); 

WAIT; 

WAIT; 

STOP 

Notice that the constants defined in the #define statement are written in upper case. This is standard 
practice in C and makes it easy to distinguish our variables from our constants. 

We can clean up the above program by putting all those #define statements in a separate file called 
NEWC.H -- then we delete them from the main program and substitute the statement #include 
<newc.h> in their place. When we compile the program, the contents of the file NEWC.H will be 
added to the main program. 

Line 4 is our function name. Remember, all C programs must contain the function main(). 

Line 5 marks the beginning of the function. 

Line 6 declares a variable of type character. 

Line 7 should look a bit strange to you. Here we're declaring two arrays of type character. 

Remember, C doesn't have a data type for strings. We declare character arrays whenever we need a 
string. 
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In this example, we're declaring two character arrays, one to hold a first name and another to hold a 
last name. We've set aside 20 bytes for each, which means the longest name each array can hold is 
19 letters (one byte is used for the null char). 

The syntax for declaring an array is the name of the array followed by the number of bytes (within 
brackets) we wish reserved for it. As with any declaration, we may declare as many arrays as we like 
on one line, as long as they are separated by commas. Remember, the line must end with a semi¬ 
colon. 

Line 9 brings us back to familiar territory. Here we are printing our first prompt. 

Line 10 shows a new use for the scanf() function. The conversion specification %s tells scanf() to 
expect the input of a string. The corresponding argument is the address where we wish the string 
stored. 

Notice something a bit different about this pointer? In the last chapter, when we were using this 
function to get integer values, each variable name was preceded by an ampersand, telling the 
compiler that we wanted the address of the variable not its value. There's no ampersand here, 
though. That's because array names are pointers. The value of fname is the address of the first byte 
of the array. 

Line 11 prints a blank line after the first prompt. 

Line 12 prints our second prompt, but with an extra something special. If you take a close look at this 
line, you'll see that %s again. In the argument list, you'll also note the array fname. The %s works just 
like %d except it tells printfQ to substitute a string instead of an integer. 

Line 13 calls scanf() again to allow input of the last name. 

Line 14 prints another blank line. 

Line 15 prints out our program's final message. Notice that there's no text in the control string -- only 
conversion specifications and newline characters. So where's all the text coming from? 

Look at the control string. The function is being instructed to print three strings, followed by two 
newlines. The strings that'll be substituted for the conversion specifications are in the argument list. 
The first string will be the string constant TEXT, which we defined at the beginning of the program. 
The second and third strings are the first and second names we previously input with scanf(). 

Line 16 and 17 wait for a keypress. 

Line 18 marks the end of the program. 

Some Fancy Stuff 

Now that we know how to use printf() and scanf() in their most basic form, it's time to take a look at 
some of the tricks we can do with them. 

All along, you've probably been wondering what the "f" in each of these function names stood for. 
Well, your wondering is over. It stands for "formatted." Both printf() and scanf() allow us to format 
input and output in various ways, as well as to do "type conversions." First, let's take a closer look at 
printf(). 

In the last chapter I gave you a list of conversion specifications that could be used with printfQ and 
scanf(). The output of printfQ can be edited by adding conversion specification modifiers. Here are 
some examples: 

%3d, %03d, %-5d, %ld, %5.3f. 

The first of the specification modifiers above sets the minimum field width to 3. If the number or 
string is smaller than the minimum length, the field will be padded with spaces. If the data to be 
printed is larger than or equal to the minimum length, it'll be printed normally. 
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In the second modifier the leading 0 in the conversion specification causes the field to be padded 
with 0's rather than spaces. The -5 in the third causes the data to be left justified (-) in a minimum 
field length of 5. The fourth tells printfQ that the matching data should be interpreted as long rather 
than int. The final example shows how to edit floating point numbers. Here, the data will be printed 
with a minimum field length of five and with three decimal places following the whole number 
portion. 

The following is a program example that utilizes the above editing techniques. 

#include <stdio.h> 
main () 

{ 


int num= 
char ch; 

5555; 

printf ( 

">%d<\n", num ); 

printf ( 

">%10d<\n" , num ); 

printf ( 

">%010d\n", num ); 

printf ( 

">%3d<\n", num ); 

printf ( 

">%-10d<\n", num ); 

printf ( 

">%f<\n" , 3.14159 ); 

printf ( 

">%2.3f<\n" , 3.14159 ); 

printf ( 

">%10.4f<\n" , 3.14159 ); 

printf ( 

">%-10.4f<\n" , 3.14159 ); 

ch = getchar(); 


} 


When the above program is run, the output looks like this: 

>5555< 

> 5555< 

>0000005555< 

>5555< 

>5555 < 

>3.14159CK 
>3.142< 

> 3.1416< 

>3.1416 < 

The arrows in the output mark the beginning and ending of each field. Notice that floating point 
numbers are automatically rounded when we limit the size of the decimal portion. Also, take a look 
at the way the variable num is defined in this listing. This form of the declaration allows you to assign 
a value to the variable immediately. 

The following program uses a similar technique to format strings. 

#include <stdio.h> 

#define TEXT "strings" 
main () 

{ 

char ch; 

printf ( ">%s<\n", "strings" ); 
printf ( ">%10s<\n" , TEXT ); 
printf ( ">%-10s<\n", "strings" ); 
printf ( ">%10.5s<\n" , TEXT ); 
printf ( ">%-10.5s<\n" , "strings" ); 
ch = getchar(); 

} 

The output of the above program looks like this: 
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>strings< 

> strings< 

>strings < 

> strin< 

>strin < 

The formatting features work much the same way with strings as with numerical data. As a matter of 
fact, the only real difference between the two is that, when we use the precision modifier (the 
number after the decimal point), it refers to the number of characters we wish printed, rather than 
the number of decimal places. 

Type Conversions 

One of C's handy — and dangerous — features is the ability to convert from one data type to another. 

I say "dangerous" because C doesn't check for type mismatch and will allow us to do all sorts of 
strange things without complaining in the least. If we're not careful, this can lead to some hard-to- 
find problems. 

The printf() function won't complain either, as long as we have the right number of arguments. We 
can print our data out in just about any form we want. The trick is the proper use of the conversion 
specifications. If we have a decimal number we'd like printed in an octal form, we just use the %o 
conversion specification. We can even convert between decimal and character. 

The following is an example of using printfQ for type conversions. 

#include <stdio.h> 
main () 

{ 


char ch; 


printf ( 

"Decimal: %d\n", 100 ); 

printf ( 

"Hexadecimal: %x\n", 100 ); 

printf ( 

"Octal: %o\n" , 100 ); 

printf ( 

"Character: %c\n", 100 ); 

ch = getchar(); 

} 

The output of the program looks like this: 

Decimal: 

100 


Hexadecimal: 64 
Octal: 144 
Character: d 

Odds and Ends 

In these beginning chapters, we've taken advantage of many I/O functions, such as printf() and 
scanf(). These are handy for general use, but as we learn more about C -- especially about using C 
with GEM — we'll outgrow them. 

You should note that the C language really doesn't support I/O routines at all. The functions we've 
been using have been added for the programmer's convenience and shouldn't be considered an 
integral part of the language. 
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CHAPTER 3 - LOOPING AND IF STATEMENTS 

I HOPE YOU'VE KEPT up with your studying, because in this chapter we're going to get down to 
serious business. Looping structures are on our agenda, as well as more about functions. And, just so 
we end up with something useful, the sample program I've chosen incorporates a function that 
should prove useful in the future — a sort routine. 

Onward 

It's typing time again. Type in the program shown at the end of this chapter (page 30) and compile it. 

When you run the program, you'll be asked how many numbers you wish to sort. Enter a number 
between 1 and 10, and then press Return. You'll be asked to enter each of the numbers. When you're 
done, the numbers will be sorted in ascending order and printed to the screen. A program run looks 
something like this: 


How many numbers? 5 

Enter 

number 

1 

56 

Enter 

number 

2 

25 

Enter 

number 

3 

12 

Enter 

number 

4 

99 

Enter 

number 

5 

12 

Sort 

complete 

I 


12 12 

25 56 99 



Digging In 

Now let's take a good look at this program's innards. Since this one's much longer than any of the 
others we've done, you might want to number each line in your listing so you can follow the 
explanation more easily. I include blank lines when numbering. 

Lines 1 through 6 are comments. A comment starts with "/*" and ends with Everything the 
compiler finds between the two is as good as invisible. Comments allow us to document our 
programs within the source code itself. 

Line 7 instructs the compiler to add the contents of the STDIO.H file to our program. 

Line 8 instructs the compiler to add the contents of the OSBIND.H file to our program. 

Line 9 defines the symbolic name MAX as 10. This is the maximum number of values to sort. Take a 
quick look at the listing. MAX is referenced in three places. If we didn't use the define statement, 
we'd have to substitute the number 10 for each occurrence of MAX. When we wanted a different 
maximum, we'd have a lot of changes to make. The #define allows a modification by simply changing 
the value assigned to MAX at the start of the program. See how handy this is? Imagine how much 
time it would save you if you were working on a thousand-line program. 

Line 16 is a function name. 

Line 17 marks the beginning of the function. 

Line 18 declares the variable num as type integer. 

Line 19 declares val as an array of type integer. Because we used the symbolic name MAX to 
dimension its size, this array will contain 10 elements, 0 through 9. 

Line 20 declares the variable ch as type character. 

Line 22 gives us something new to discuss. Here we're calling the function how_many(), Line 35, and 
assigning the value it returns to the variable num. This will be the number of items we want to sort 
(not to be confused with MAX, which is the maximum items). Notice that this function call has the 
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same format as another we've used quite frequently, ch=getchar(). All function calls work the same, 
whether we're calling a library routine like getchar() or our own function. 

Line 23 calls another of our functions, get_nums(). Since this function doesn't return a value, we 
aren't assigning its return to a variable. We simply call it by name, just like printf(). We do, however, 
have to pass arguments to the function: num (the number of values we wish to sort) and val (the 
beginning address of the array where we'll store the values). 

Line 24 calls sort(), the function that does the sorting. This function doesn't return a value either, but 
it must be passed the same arguments as get_nums(). 

Line 25 calls outputQ, the function that prints the sorted numbers to the screen. It requires the same 
arguments as the two previous functions. 

Line 26 waits for us to press a key. This statement probably looks pretty alien to you. I'm going to ask 
you to take it on faith for now. 

Line 27 marks the end of the function. 

The Golden Moment 

We've now stumbled upon the perfect time to discuss structured programming techniques. Our 
function main() is constructed so that anyone can easily see what's going on. Each function call 
performs a logical step in the sequence of actions that must be completed in order to sort our 
numbers. 

This type of construction matches the way people think. When you're going to make a lunch of beans 
and hot dogs, you don't consciously dwell over all the details in each step. Your thoughts would run 
like this: First heat the beans, and then boil the hot dogs and put them in the buns. 

But there are many details you take for granted: what about taking the pans out of the drawer and 
placing them on the stove? Don't forget, you've got to open the can before you can get to the beans. 
And where did the hot dogs come from? Did you open the refrigerator? Who turned on the stove? 

We don't worry about these minor details, because, if we did, we'd get so confused we'd starve. A 
programmer should think in this same structured way. Projects that seem impossible when we're 
mired in details become a snap when viewed from a more general viewpoint. 

It's this form of thinking that's the essence of structured programming. To get our sort routine 
working, all we have to do is find out how many items there will be, get the items, sort them, and 
then print them out. At this point, we're not concerned with how we're going to do each of these 
steps. One thing at a time, slow and easy. 

When we have the general logic worked out, then we can get into the details, taking each step and 
writing a function to accomplish it. In large programs, this process becomes even more important. 
Using structured techniques will make your job much easier and will result in very readable code. 

Back to the Program 

Line 35 is a function name. This is the function called from Line 22. 

Line 36 marks the start of the function. 

Line 37 declares the variable n as type integer. 

Line 39 sets n equal to the value of MAX+1, or, in this case, 11. 

Line 40 is the start of a while loop. This type of loop will repeatedly perform a statement or series of 
statements as long as the expression within the parentheses remains true. Here's another example: 
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while ( z > 2 && ch != 'e' ) 


This line is read: while z is greater than 2 and ch doesn't equal the letter "e." C uses some unusual 
character combinations for operators. The double ampersand (&&) is the equivalent to BASIC's AND. 
The "!=" is the symbol for "not equal to." It's the opposite of another operator we learned a while 
back, Remember the difference between "==" and "="? 

We're using a while loop here to insure the input of a value no larger than MAX. Looking back, Line 
35 initializes n, the variable we're using in the conditional expression, to a value greater than MAX. If 
we didn't do this, we might not get a chance to enter our number. Whatever garbage happened to 
be in the memory location we labeled n would be used to evaluate the conditional expression. If it 
was less than MAX, the loop would be skipped and whatever value n happened to contain would be 
passed to the program. 

If you don't initialize your variables, they'll contain whatever value happened to be in the address 
they were assigned. 

The brace following the while statement marks the beginning of the statements within the loop. 
Whenever a loop contains more than one statement, the start and end of the loop are marked with 
left and right braces, just like a function. The braces are not necessary if a loop contains only one 
statement. Here's an example of a single statement while loop: 

while (x<5) x = x + 1; 


Line 41 prints a prompt. 

Line 42 accepts a number from the keyboard and assigns it to the integer n. 

Line 43 prints a blank line. 

Line 44 marks the end of the loop. At this point, the value of n is checked, and if it's greater than 
MAX, the loop repeats. This will continue until the user enters a number less than MAX. 

Notice the indenting of the statements that make up the loop. This isn't required, but makes our 
programs much more readable, by clearly delineating the body of the loop. 

Line 41 introduces us to the return statement. Whenever a return is encountered, control is passed 
back to the calling function, along with the value in parentheses. The return may be anywhere within 
the function. If you don't want to pass a value, delete the parentheses. In this case, we're sending the 
value n back to main(), where it will be stored in the variable num. 

The variable n in how_many() is a local variable. It's created when the function is called and 
destroyed when control is passed back to the calling function. It has no relationship with other 
variables in the program (except maybe num, which will get only its value). You could even have 
another n elsewhere in your program without conflict. 

Arguments in C are passed "by value" rather than "by reference." This means that only the values of 
the arguments are passed, not their addresses. The original values are safe from change. If we want 
to access a variable by reference, we must pass the address using a "pointer." We'll discuss pointers 
a little later on. 

Line 46 marks the end of the function. 

Line 58 is a function name. This function is called by Line 21. Notice something a little different here? 
There are two variables enclosed in the parentheses, which means two arguments are being passed 
from the calling function. The argument's values will be stored in n and v and are passed between 
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the functions in the same order in which they appear in the function call; that is, n receives the value 
of num, and v receives the value of val. 

Line 59 tells get_nums() that it should interpret the data being passed into n as an integer. All 
arguments within the function name's parentheses must be defined, and you must do so before the 
beginning brace. 

Line 60 tells the function that v is an integer array. We're not dimensioning the size of v, since it's 
really the same array we dimensioned in Line 18 (val[]). How can that be? Aren't arguments in C 
passed by value, not address? So how can v[] be the same array as val[]? Why am I asking all these 
silly questions? 

I'll tell you why. Because I'll bet you forgot that an array name without an index is an address, val is 
being passed as I described previously, but its value is the address of the array's first byte. What does 
this mean to us? It means that we're very definitely going to be monkeying with the contents of the 
original array. It's not safely protected from our clumsy fingers like num is. 

Line 61 marks the start of the function. 

Line 62 declares some local variables. These variables exist only in the function. They're forgotten the 
second we exit. 

Line 64 gives you a look at a new looping technique. The for loop in C is very similar to the 
FOR...NEXT loop in BASIC. Its syntax is the keyword for followed by three expressions within 
parentheses which define the limits of the loop. The three expressions are separated by semicolons. 

The first expression initializes the loop variable. In Line 56, we're setting x to 0. The second 
expression is the condition that controls the loop. As long as this condition yields a true result, the 
loop will continue executing. The third expression is the loop's step value or reinitialization. Line 56 in 
BASIC would look like this: 

FOR X=0 TO N-l STEP 1 


Of course, in BASIC we don't need the "STEP 1," since it's assumed. I just included it for purposes of 
clarity. 

What do you think of that ++x in Line 56? Got any ideas? This expression performs the same 
calculation as x=x+l. As a matter of fact, we can use either form of the expression in C, although the 
former is preferred because it's shorter. The two plus signs together form the C increment operator. 
There is also a decrement operator which is, of course, made up of two minus signs. These operators 
may be placed before or after the variable; however, there's a subtle difference. The expression ++x 
increments x before the value is used. The expression x++ increments x after the value is used. For 
example, let's say that x starts with a value of 1. Then z = ++x will set z equal to 2, whereas z = x++ 
will set z equal to 1. 

The brace following the for statement marks the start of the loop. 

Line 65 prompts the user for a number. The prompt uses the value of x to tell the user which value 
he's entering. 

Line 66 gets the number the user types from the keyboard and stores it in the variable num. Note 
that this variable has nothing to do with the variable num declared in main(). 

Line 67 stores the number into the storage array's next element. In C, arrays are indexed just as in 
BASIC. In our first pass through the loop, x has a value of 0. Therefore, the first element of the array 
(in the context of our function, the first element is v[0], but this is really the element of our original 
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array, val[0]) gets the first number input. As x gets incremented, each consecutive element of the 
array is filled with its appropriate value. 

Line 68 moves the cursor to the next line. 

Line 69 marks the end of the loop. 

At this point, x is incremented, and the control statement is evaluated. If the result is true, then 
another iteration of the loop is performed. This continues until the loop's condition evaluates to 
false. 

Line 70 passes control back to the calling function, main(). There are no parentheses in the return 
statement because we aren't sending a value back. 

Line 71 marks the end of the function. 

Line 81 is a function name. This function is called from Line 22. The same arguments are being passed 
as in our call to get_nums(). 

Line 82 defines the first argument as integer. 

Line 83 defines the second argument as an integer array. 

Line 84 marks the beginning of the function. 

Line 85 defines some variables of type integer. 

Line 87 initializes the variable used to evaluate the conditional expression in the following while loop. 
This ensures that we enter the loop properly. 

Line 88 is the beginning of our while loop. 

Another Break in the Proceedings 

Before we get too far into this function, I should give you a little background on the sort. We're going 
to use a "bubble" sort, one of the simplest (and slowest). It works like this: We compare the first two 
values in the array and switch them if they're in the wrong order. We then compare the second and 
third values and switch them if necessary. We continue this process until the last value in the array 
has been compared, at which point, the highest value will have been "bubbled" up to the top. We 
then start all over, repeating the loop until we make it through the array without a switch. 

Back To It 

Line 89 marks the beginning of the body of the while loop. 

Line 90 turns off the "switch" flag. If this variable retains the value of 0 through the next loop, then 
the sort is complete. 

Line 91 sets up a for loop; we will use the loop variable for an array index. This will move us through 
the array, element by element. 

Line 92 should be strangely familiar. This is C's version of the IF...THEN statement. Its construction is 
very similar to its BASIC counterpart, but there are two differences. First, the expression that follows 
the if is always within parentheses. Second, don't include the word "then." The body of the if 
statement is constructed following the same rules that apply to loops. If you have more than one 
statement, the entire block must be enclosed in braces. A single statement may be placed after the if 
statement with no braces. 

Our if statement compares two consecutive elements of the array that contains the values to be 
sorted. If the first is larger than the second, the statements contained in the braces are executed, 
switching the two array elements. If they're already in the proper order, the switching is skipped. The 
next iteration of the for loop is then initiated. 


Port: HYPertext by Lonny Pursell & PDF by DrCoolZic (jig) - VI.0 Oct. 2010 


Page 31/321 


C-MANSHIP COMPLETE - by CLAYTON WALNUT 


Line 93 marks the beginning of the body of the if statement. 

Line 94 is the first step of the switch. The value in v[x] is placed in temp. 

Line 95 stores array element v[x+l] into v[x]. 

Line 96 places temp (originally v[x]) into v[x+l], and the switch is complete. 

Line 97 sets the "switch" flag to its true condition, so the loop will be performed again. 

Line 98 marks the end of the if statement. 

Line 99 marks the end of the while loop. 

Line 100 returns control to the calling function — in this case, main(). 

Line 101 marks the end of the function. 

Line 111 is a function name. 

Line 112 declares the first argument passed to the function. 

Line 113 declares the second argument passed to the function. 

Line 114 marks the beginning of the function. 

Line 115 declares the integer variable x. 

Line 117 prints a message. 

Line 118 initiates a loop to print the sorted array values. 

Line 119 prints the array values using the loop variable as an index. 

Line 120 prints a blank line. 

Line 121 returns control to main(), the calling function. 

Line 122 marks the end of the function. 

Take a Breath 

We covered a lot of material in this chapter. If you're still with me, pat yourself on the back; you've 
learned most of what you need to know to write usable C programs. In the next chapter, we'll 
continue studying, but we'll also have some fun. 
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Program Listing #1 


/********************************************/ 

/* 

C-MANSHIP 

*/ 

/* 

Chapter 3 

*/ 

/* 

Listing 1 

*/ 

/* 

Developed with Megamax C 

*/ 

j-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k'k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-kj 


#include <stdio.h> 

#include <osbind.h> 

#define MAX 10 

/'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k'k-k'k-k'k-k'k-k'k-k'k 

* main () 

* Main program 

: k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k-k'k-k'k-k'k-k'k-k'k-k-k-k-k-k'k-k'k-k-k-k-k-k-k'kj 

main () 

{ 

int num; 
int val[MAX]; 
char ch; 

num = how^many (); 
get nums ( num, val ); 
sort ( num, val ); 
output ( num, val ); 

Cconin (); 

} 
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/■k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k 

* how many () 

~k 

* Retrieves from user the # of values to be 

* sorted and returns that value to main (). 

' k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-kj 

how_many () 

{ 

int n; 

n = MAX +1; 

while ( n > MAX ) { 

printf ( "How many numbers? " ); 
scanf ( "%d", &n ); 
printf( "\n\n" ); 

} 

return ( n ); 

} 

J'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k'k 

* get_nums () 

* 

* Retrieves from user the values to be sorted 

* and stores those values in the array v[]. 

* Input to the function is the number of values 

* to be sorted and the address of the array in 

* which to store the values. 

kk'k-k'kk'k'k-kk'k-k-kk'k-k-kkk-k-k-k'k-k'kk'k-k'kk'kk-k-k'k-k-kk'kk-kk'kk'k j 

get_nums ( n, v ) 
int n; 
int v[]; 

{ 

int x, num; 

for ( x=0; x<n; ++x ) { 

printf ( "Enter number %d: ", x+1 ); 
scanf ( "%d", Snum ); 
v[x] = num; 
printf ( "\n" ); 

} 

return; 

} 
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/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* sort () 

k 

* Uses a bubble sort to sort the #'s stored in 

* the input array. Input to the function is the 

* number of values to be sorted and the address 

* of the array in which the values are stored. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

sort ( n, v ) 
int n; 
int v[]; 

{ 

int swtch, x, temp; 
swtch = 1; 

while ( swtch == 1 ) 

{ 

swtch = 0; 

for ( x=0; x<n-l; ++x ) 

if ( v[x] > v[x+l] ) 

{ 

temp = v[x]; 
v[x] = v[x+1] ; 
v[x+l] = temp; 
swtch = 1; 

} 

} 

return; 

} 

jkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* output () 

k 

* Prints the sorted values to the screen. The 

* input to the function is the # of values to 

* print and the address of the array where the 

* values are stored. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

output ( n, v ) 
int n; 
int v[]; 

{ 

int x; 

printf ( "Sort complete!\n\n" ); 
for ( x=0; x<=n-l; ++x ) 

printf( "%d ", v[x] ); 
printf( "\n\n" ); 
return; 

} 
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CHAPTER 4- FLOW OF CONTROL AND FUNCTIONS 

Feeling lucky? Good. Get out all that green stuff that's been cluttering up your wallet and give Lady 
Luck a wink. This chapter we're all going to learn how to play craps. (I know that was top priority on 
your things-l've-got-to-do-today list.) If you haven't already done so, type in the program found at 
the end of this chapter and compile it. 

Now I admit that our program isn't the most stunning version of computer craps that'll cross your 
eyeballs, but it's a good programming exercise and demonstrates a lot of new techniques. If you 
already know the rules of craps (that's where you've been all those late nights, huh?), skip ahead to 
the next section. For those who've led sheltered lives, craps is a dice game which has the dubious 
reputation for making and breaking many a fortune. In our case, we'll try to leave your savings intact 
-- only the rules remain the same. 

Step one is to roll the dice. If on your first roll you get a seven or an eleven, you win. A two, three or 
twelve, on the other hand, leaves you the loser. If you manage to avoid all lucky and unlucky 
combinations, you must roll again...and continue to do so...until you either reroll your original 
number (in which case you win) or you roll a seven or an eleven (in which case, you lose). 

The Game's Afoot (Without Toes) 

Now that you know how to play, take a moment to try the program out. Have a little fun and get a 
general idea of how the program works. 

Now let's take a look at the listing. You might want to number each line, so you can refer to them 
more easily as we go through the program. Count blank lines too. 

I don't think it's necessary to go through every line as we have in the past. You've had most of the 
basics pounded into your head, right? 

Let's skip up to Line 26. You've probably noticed that we usually use ch as a character variable. This 
time, however, we have it declared as an int. Does that mean that we've abandoned our poor friend 
ch to a new and unknown fate? No, we're still going to use it to hold character information, because 
it just so happens that the only difference between a character variable and an integer is the number 
of bytes they take up in memory. 

You may remember that a character is stored in one byte and an integer is stored in two. For our 
purposes, the two are really interchangeable. What you should be aware of is that, in C, character 
variables are converted to integers for processing, and then truncated back to a single byte. 

By declaring them as integers in the first place, you'll always be reminded of what's going on in your 
machine's innards. And you may come across a time in your illustrious programming career where 
the difference will be critical. 

Now skip ahead to Line 30. This is the beginning of the main game loop. You remember the while 
loop, right? The variable we're testing, play, was initialized to 1 (or true) in Line 28. As long as it 
retains this value, the game loop will repeat. 

Notice that we aren't using the statement while (play == 1). Any non-zero value is evaluated to true, 
therefore play==l and play are really the same expression from a Boolean point of view (when play 
does indeed equal 1); they are both true. The way to test for a false condition (0) is with the not 
operator: while (Iplay). 

The game loop is another example of structured programming. Each major task of the program has 
been allotted to a function. First we roll the dice; then we check to see if the player won, lost or has 
to roll again. If the call to check_roll() leaves the variable win in its zero state, then the second while 
loop is executed. The dice are rolled until win changes to 1 (win) or -1 (lose). 
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The variable win is then tested in an if statement, and the appropriate message is relayed to the 
player. The percentage of games won is calculated, and the player is asked if he wishes to play again. 
If he answers with a Y, then play remains true and the game loop repeats. Otherwise, play becomes 
false, and the program terminates, returning you to the desktop. 

Now the details, starting with Line 30. Here we initiate the main loop. As long as the expression in 
parentheses is true, the loop will repeat. Since we initialized play to 1, we enter the loop. The first 
thing we have to do in the loop is initialize a couple more variables. This is important, since the 
values of first and roll are passed to the function that "rolls" our dice. 

The variable first is used as a flag to indicate whether it's the player's first roll. What roll we're on is 
important. For example, a seven on the first roll is a winner, but a seven on the second roll is a loser. 
The variable roll will hold the value of the current roll (except the first one). Line 33 calls the function 
roll_dice(), and the value returned is placed in first_roll. 

Line 34 calls check_roll() and stores its return value in win. To evaluate the player's roll, check_roll() 
needs some information; so we're passing the values of first, first_roll and roll to the function. 

Line 35 sets the flag first to its false condition. If the player neither won nor lost with his first roll, the 
value of win will still be 0, and the second while loop, which begins on Line 39, will be performed. 

See the win==0? Why didn't we use the while (Iwin) construction mentioned previously? There's 
really no reason, as far as the program goes. I used the former construction to make the program 
more readable. Using Iwin might make someone looking at the source code think that if win was 0 
the player lost. This isn't true. A value of 0 means that the player hasn't won — and he hasn't lost 
either. It's a neutral state. If you want to use Iwin, go right ahead. It'll work just fine. 

Line 37 calls roll_dice() a second time. This time the variable roll is where its return value is stored. 
We need this second variable, since we need to compare the first roll with all subsequent rolls. 

Line 38 calls check_roll() again. If the value of win remains 0, meaning the player still hasn't either 
won or lost -- the loop repeats. Once the player has managed to make his roll — or has blown it, with 
a seven or eleven — we exit the loop. 

Line 40 increments the game counter, num_games. We'll use this value to calculate the percentage 
of games won. 

Lines 41 through 45 make up an if statement. It uses the value contained in win to determine the 
appropriate message to give to the player, as well as keep track of the number of wins. If win is -1, 
the player has lost, and the program prints "You lose" — deep, huh? If win equals 1, the player has 
won the game, and a statement of equal profundity is printed. Also, the counter num_win is 
incremented, keeping track of the number of games our lucky player has managed to win. 

We're also calling a new library function here, puts(). This function prints the string argument 
contained in the parentheses. The main difference between puts() and printf() is that the former has 
no formatting options. 

In the previous chapter we just touched on the format of the if statement. Now we're going to look 
at some more complex examples. The if statement starting on Line 41 is a slight variation of the one 
we saw before. The difference is the addition of the else portion. 

Thinking back, you'll remember that the body of an if statement is performed only when the 
expression in the parentheses is true. When we add the else, the rules change just a bit. We now 
have a kind of "either/or" condition. If the expression being tested is true, the statements following 
the if and preceding the else will be performed. If the expression tested is false, the statements 
associated with the else are performed. 
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The syntax rules for the else portion of the statement are the same as for the if. If the body of the 
else portion consists of more than one statement, we must enclose them in brackets, and — 
remember — each statement must end with a semicolon. 

Line 46 calls the function percent(), which prints out the percentage of games won. 

Line 47 calls the function play_again() to find out whether the player wishes to continue or quit. 

Digging Deeper 

Now that we've taken a look at the general scheme of things, we can get into the details of each 
function. 

The function roll_dice() does exactly as its name implies. The first thing you should take note of is the 
way this function is declared. There's something extra here. See what it is? Up till now, our functions 
have been declared simply by the function name. Now the key word int has been added in front of 
the name. This specifies that the value to be returned by the function will be an integer. We could 
have left the int off, since the default is always integer. 

But if we want to return some other data type from a function, we must declare the function at the 
top of our program, as well as add the data type specification to the function name itself. For 
instance, if we wanted to return a character from a function named ret_char(), we would first declare 
the function name, with it's data type, at the top of our program like this: 

char ret^char(); 

Then the beginning of the function itself might look like this: 

char ret_char(l, b) 
int 1, b; 

The variables I and b are the values being passed to the function and are included here only to 
differentiate between the two examples. 

Lines 60 through 66 declare some local variables, print a prompt and wait for Return to be pressed. 

Line 67 gets a random number and places it in dl. Random() is a function specific to the ST and is an 
extension of the BIOS (Basic Input/Output System). It returns a 24-bit random number. In our case, 
we need an integer. Take a good look at Line 74. See the int in parentheses? This is a "cast" operator. 
What we're doing is forcing the return of Random() into a 16-bit integer, rather than doing it 
implicitly through automatic conversion (just leaving the cast operator out). In this particular case, 
the statement would have worked either way, but sometimes the difference can be critical. Look at 
these two code segments: 
int i; 

i = 3.4 + 7.8; 


int i; 

i = (int) 3.4 + (int) 7.8; 


In the first example, the addition is performed, yielding a result of 11.2. Then, since the variable i is 
defined as an integer, the conversion from float to int is done automatically by truncation, making i 
equal to 11. In the second example, 3.4 and 7.8 are converted to integers before the addition is 
performed. This yields a result of 10. Not quite the same answer. 

Line 68 takes the value in dl and converts it to a positive number between 1 and 6, using modulo 
arithmetic and the absolute value function. The abs() function is defined in the STDIO.H file. It looks 
and works exactly as in BASIC, returning the absolute value of a single argument. 
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The percent sign is the modulus operator. It is used only in integer arithmetic and yields the 
remainder when the number on the left is divided by the number on the right. For example, the 
expression 6 % 4 gives a result of 2. 

So, in Line 68, we're taking the absolute value of dl (in case we got a negative number from 
Random()), dividing it by 6, then adding 1 to the remainder. Using 6 in the modulo math assures us 
we'll always get a remainder less than six (zero through five, to be exact). Adding one gives us our roll 
of the die (one through six). 

Lines 69 and 70 get a value for the second die in the same manner. The function then prints out the 
value of each die, as well as the total. The total, t, is then passed back to main(). 

Line 89 declares the function check_roll() as returning an integer. Three values are being passed to 
the function. Notice that the variables being passed (Line 34) and the variables accepting the values 
have the same names. This is purely for reasons of clarity. They're still completely separate identities. 

Now look at the body of the function. This is surely the most complex piece of code we've tackled 
yet. Basically, the whole thing is an if statement, but with layer upon layer. This function will give you 
great insight into the problems inherent in nested if statements. 

Before we get too far into this function, I should introduce you to the else if construction. I 
mentioned previously that, with the if...else statement, we have an either/or situation. The else if 
takes this one step further, and allows us to add a test to the else portion of the statement. Look at 
this example: 


if (expl) statement!. ; 
else if (expr2) statement2; 
else statement3; 


If expl is true, statementl will be executed and the elses ignored. If expl is false, exp2 is tested. If 
we get a true result, statement2 is executed and the final else is ignored. Finally, if both expl and 
exp2 are false, statements is executed. 

In check_roll(), we're using the flag first to decide which set of "rules" apply to the player's roll. If it's 
his first roll, first will be equal to 1, and we'll evaluate the second if statement, which checks to see 
whether the roll was a seven or an eleven. If it was, the player wins. The flag wn is set to 1, and the 
program continues at Line 103. 

See those vertical bars in the middle of Line 96? That's the logical OR operator. Line 96 reads: if 
first_roll equals seven or first_roll equals eleven. The logical OR operator yields a true result if one or 
more of the expressions are true. Here are a couple of examples: If we assume that a equals 1, b 
equals 2, and c equals 3, the following expressions evaluate as shown: 


a==l || b==6 TRUE 

a==4 || b==2 TRUE 

a==l || b==2 TRUE 

a==2 || b==5 FALSE 

a==3 || b==3 || c==3 TRUE 

a==l || b==5 || c==3 TRUE 

a==2 || b==3 || c==4 FALSE 


Continuing with check_roll(), if the roll wasn't a seven or eleven, we evaluate the else if portion of 
the statement. Here we check for a two, three or twelve. If we find one of these values, the player 
loses. The flag wn is set to -1, and, as in the first case, program execution continues at Line 103. If 
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neither of the previous conditions are true, wn retains its initialized value of 0 (Line 94), and once 
again, the program continues at Line 103, which returns the value of the flag to main(). 

Whew! All that's only if the player's on his first roll. If first is 0, program execution jumps to the else if 
statement on Line 101. 

Before we continue, I'd like to see if I can help you avoid a good deal of teeth-gnashing and hair¬ 
pulling in your future C programming. Look at those brackets on Lines 95 and 100. They're absolutely 
essential with nested if statements containing else constructions. Without those brackets the 
compiler 

has no way of knowing that the last two else if statements go with the outer if and not the inner. 
Keep in mind that the indenting is only cosmetic; it means absolutely nothing to the compiler. This is 
an easy trap to fall into, since the indenting makes everything so clear to the programmer. Just 
remember - use brackets. 

Now let's take the second possible path in this function. If first is 0, all the stuff between the brackets 
is skipped, and we continue at Line 101. This line checks to see whether the player's roll was equal to 
his first. If it was, wn is set to 1 (win), and its value is returned to main() at Line 103. 

If the first condition isn't true, we drop down to test the second. Line 102 checks for a roll of seven or 
eleven. If it evaluates to true, wn is set to -1 (lose), and its value is returned at Line 103. 

If none of the above conditions are met, the only thing that happens in this function is that wn is set 
to 0 (Line 94) and its value is returned to main() (Line 103). The player has neither won nor lost and 
must roll again. This process repeats until wn -- and, subsequently, win - gets a non-zero value. 

Moving on, Line 112 begins the function percent(). The word VOID in front of the function name 
indicates to the programmer that the function doesn't return a value. Like the int in some of the 
previous functions, it could've been left off. VOID is really just an empty comment. In other words, 
even though we've labeled percentQ as VOID, it's still capable of returning an integer value. We're 
writing it this way for the sake of clarity only. 

This function does nothing more than calculate the percentage of games won and print the result out 
to the player. A few things should be said about Line 117, though. 

First of all, in case it isn't obvious, the "/" (not to be confused with the backslash) is the division 
operator. The value on the left of the operator is divided by the value on the right. You'll notice that 
the integer variables num_win and num_games are being cast to floating point. This is critical in this 
calculation. 

When we divide integers in C, we get an integer result; the decimal portion is truncated. If we allow 
this to happen with our percent calculation, we'll get two possible results, only one of which will be 
accurate. If we've won every game, num_win/num_games will give us 1, which multiplied times 100 
equals 100%. Fine and dandy. But what happens if we've only won one game out of two? In integer 
division, num_win/num_games will give a result less than 1. When the decimal portion is truncated, 
we'll end up with 0. And what's 0 times 100? It's certainly not 50%, the result we want. 

Okay, we're almost done. Just one more function to look at. The function play_again() is responsible 
for finding out if the player wants to play another game. There's really nothing very new here. 
Something that we had a brief encounter with was the way we're using getcharQ in Line 133. We 
could rewrite this line as follows: 

ch = getchar(); 

if (ch == 'Y' || ch == 'y'); 
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One of the neat things about C is the way we can cram a lot of stuff on one line. Here, getchar() is 
called, and its returned value is stored in ch and compared to the character "Y." The variable ch is 
also compared to the character "y." If either of these compares finds a match, the flag p is set to true 
and returned to main(), to be evaluated at Line 47. This way, the game repeats until the call to 
play_again() results in a 0. 

Breathing Time 

That's it — class dismissed. If any of the program is still fuzzy to you, study up on it, especially the 
function check_roll(). When you feel you've got it all down pat, try your hand at writing a simple 
game. How about that classic guess the number game? It should be fairly easy to write. Have the 
computer pick a random number between 1 and 100. As the player tries to guess the number, have 
the computer tell him whether he's too high or too low. When you've got the program working, 
follow me over to the next chapter. 

Program Listing #1 

/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* C-MANSHIP * 

* Chapter 4 * 

* Listing 1 * 

* Developed with Megamax C * 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 


#include <stdio.h> 

#include <osbind.h> 

#define VOID /**/ 

/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* main () 

k 

* Main Program 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkj 

main () 

{ 


int 

first roll. 

/* 

Value of player's first 

roll. */ 


win. 

/* 

Win, loss or no change flag. */ 


roll, 

/* 

Value of player's rolls. 

*/ 


play. 

/* 

Game play continue flag. 

*/ 


first; 

/* 

First roll flag. */ 


int 

num win = 0; 

/* 

Number of games won. */ 


int 

num games = 0; 

/* 

Number of games played. 

*/ 

int 

ch; 

/* 

Single character storage 

. */ 
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play = 1; 
win = 0; 
while (play) { 

first = 1; 
roll = 0; 

first roll = roll_dice(); 

win = check roll (first, first_roll, roll) 

first = 0; 

while (win == 0) { 

roll = roll dice(); 

win = check_roll (first, first roll, 

} 

++num games; 

if (win == -1) puts ("You lose. "); 
else { 

++num_win; 

puts ("You win! "); 

} 

percent(num games, num win); 
play = play_again(); 

} 

} 


/■k'k-k'k'k-k'k-k'k-k'k-k'kic'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k 

* roll_dice () 

•k 


* Retrieves a random number from 1 to 6 for each die 

* and calculates the total, reporting the sum to 

* the player. 

'k-k'k-k'k'k-k'k-k'k-k'k-k'kk'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'kk'k-k'k-k/ 


int roll_dice() 
{ 

int dl, 
d2, 
t; 

int ch; 


/* Value of die 1. */ 

/* Value of die 2. */ 

/* Total of dice. */ 

/* Character storage. */ 


puts ("Press RETURN to roll:\n"); 
ch = getchar(); 
dl = (int) Random(); 
dl = abs(dl) % 6 + 1; 
d2 = (int) Random(); 
d2 = abs(d2) % 6 + 1; 
printf ("Die #1: %d ", dl); 
printf ("Die #2: %d\n\n", d2); 
t = dl + d2; 

printf ("Your roll: %d\n\n", t); 
return (t); 


roll); 
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! •^•k'k-k'k-k-k-k'k-k'k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k'k-k-k-k-k-k-k-k-k-k-k-k-k'k-k'k-k'k-k'k-k-k'k'k-k-k-k 

* check_roll () 

k 


* Checks to see whether the player has won, lost or 

* must roll again. The input is a flag indicating 

* whether this is the first roll of the game, the 

* value of the first roll, and the value of the 

* current roll if it applies. The output is a -1 

* for a lose condition, 1 for a win condition, and 

* a zero if the player must roll again. 

k'kk-kk-kk-kk'kk-kk-kk-kk-k-k-kk-kk-kk-kk-kkk-kk-kk-kk-kk-kk'kk-kk-kk-kk-k-k'k-k'k! 

int check roll(first, first roll, roll) 
int first, first_roll, roll; 

{ 

int wn; 


} 


wn = 0 ; 

if (first == 1) { 

if (first roll == 7 
else if (first roll 
first_roll == 
first roll == 

} 


I| first_roll == 
== 2 | 

3 I I 

12 ) wn = -1; 


else if (first roll == roll) wn = 1; 
else if (roll == 7 || roll == 11) wn = -1; 

return (wn); 


11 ) 


wn 


I'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k'k-k'k-k'k-k'k-k'k-k'k 

* percent () 

■k 

* Calculates & reports the percentage of games won. The 

* input is the # of games played & the # of games won. 

■k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k/ 

VOID percent (num games, num win) 
int num games, num win; 

{ 

float pc; 


1 ; 


pc = ((float) num win / (float) num games) * 100.0; 
printf ("You've won %d %% of the games\n", (int) pc); 

} 

j •kk-k-k-kk-k-k-kk-kk-k-k-k-kk-k-k-k-k-k-k-k-k-kk-k-k-kk-kk-kk-k-k-kk-kk-kk-k-k-kk-k-k-kk-k-k 

* play_again () 

k 

* Asks the player if he wants to play again, & returns 

* a boolean value based on his answer: yes=l and no=0. 

■k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-kj 

int play_again () 

{ 

int p; 
int ch; 

puts ("Play again? "); 

if ( (ch = getcharO) == 'Y' | | ch == ' y' ) p = 1; 

else p = 0; 
puts ( "\n\n" ); 
return (p); 

} 
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CHAPTER 5 - STORAGE CLASSES AND ARRAYS 

Okay, Pass Your Homework to the front of the class. What was that? Did I hear someone in the back 
say, "What homework?" 

For those who need their memories refreshed, in the previous chapter I suggested that you try 
writing a C version of a simple number-guessing game. You were to have the computer pick a 
number from 1 to 100; then allow a player to enter guesses. With each guess, the player was to 
receive a clue as to whether he was too high or too low. 

My solution for this project is found in Listing 1. Does your program look something like this? Maybe, 
maybe not. At this early point in your C career, I think the following qualities are most important. 

First of all, does your program work? If you can give me an affirmative, you've earned 70 points. At 
this stage of the game, getting programs up and running is a very large part of the battle. 

Now, did you use a structured approach? Does the function main() concern itself with the major 
steps of the game, allotting details to other functions? If so, give yourself 20 more points. When you 
become more familiar with C, this area will be more pointworthy. In fact, eventually, an unstructured 
program will be an automatic zero. Strict, huh? 

Finally, how readable is your code? Have you used indentation? Are there blank lines between each 
function? Did you use meaningful and descriptive names for your functions and variables? Are there 
enough comments? Do the comments adequately describe the purpose of the function? Another 10 
points to those who've added these touches of elegance. 

Game Time Again 

Now that you've tallied up your homework score, type in Listing 1 and compile it. To play the game, 
run the program and follow the prompts. Everything work okay? Let's examine this program in detail. 

main() is written in a manner that makes the program's general operation quite apparent. The details 
are taken care of in other functions. Put simply, the program is structured. 

We start off by initializing the flag play to TRUE. This will get us into the while loop at Line 23. As long 
as play is true, this loop will repeat, allowing the user to play as many games as he wants without 
rerunning the program each time. 

Once in the loop, we must initialize some variables. The counter turns tallies the player's guesses. 

The flag win tells main() when the player has made a correct guess. 

After initializing the variables, we call the function getnum(), which returns a random number 
between 1 and 100. Next, since we had the forethought to initialize win to FALSE, we enter the while 
loop at Line 27. This loop will repeat until win becomes TRUE, keeping the player guessing until he 
comes up with the right number. 

In the body of the loop, we increment the turn counter, get the player's guess and check if he's right. 
If he's not, win remains FALSE and the loop repeats. If the number has been guessed correctly, 
program execution drops through to Line 32, where the player is told how many guesses were made. 

Line 33 calls play_again() to see whether the player wants to continue. If so, the flag play remains 
TRUE, and the outer while loop repeats. When play becomes FALSE, the program ends, and the user 
is returned to the Desktop. 

Easy, right? You should've followed all of the above explanation with little difficulty. 

The other functions are just as simple. The function get_num() uses the same method we 
incorporated last chapter in our dice game to get a random number. The only difference is that now 
we're getting a number between 1 and 100 rather than one between 1 and 6. 


Port: FlYPertext by Lonny Pursell & PDF by DrCoolZic (jig) - VI.0 Oct. 2010 


Page 44/321 


C-MANSHIP COMPLETE - by CLAYTON WALNUT 


The function get_guess() incorporates a while loop, forcing the player to enter a number within the 
proper range. The loop will repeat until the gamester bends to our will. 

The function check_guess() checks whether the player's guess was too high, too low or right on the 
money, and then prints the appropriate message. If the player has guessed right, then wn is set to 
TRUE (and thus win becomes TRUE, too), and the game is over. 

Finally, the function play_again() asks whether the player wants another whack at it. Once again, we 
use a while loop to guarantee a proper response. 

Some Classy Information 

Before we take a look at the next two listings, we need to discuss a fun topic called "Storage Classes." 
All the variables you define in your C programs have a storage class, whether you're aware of it or 
not. In our previous program examples, the storage classes were set automatically. We didn't have to 
concern ourselves with the details. That's all fine and dandy for a beginner, but sooner or later we're 
going to have to know how our variables are treated by the system. 

There are four C keywords that refer to the storage classes. They are: extern, auto, static and 
register. 

The keyword extern stands for external. Any variable that's not defined within a function, one that is 
external to the function, falls into this class. Both Listing 1 and Listing 2 contain examples. Notice the 
arrays week[] and weeks[]. 

Unlike local variables that disappear once we're through with them, external variables may be 
accessed anywhere within your program. The only rule to remember is that, if their declaration 
appears in another file or after a function that refers to them, they must be declared as external in 
the function where they're used. Here's a declaration example: 


extern int numbers; 


Automatic (or auto) variables are those declared within a function. They remain healthy and happy as 
long as we stay within the function where they were declared. The moment we exit, they vanish into 
that great CPU in the sky. It's not necessary to declare these variables by their storage class (we 
never have, right?)--but, if you wanted to, this is what the declaration would look like: 


auto int number; 


Variables of the class static are similar to automatic variables, except their values aren't forgotten 
when the function is exited. Don't try to access them in other parts of your program, though; they're 
still strangers there. Look at this code fragment: 

main () 

{ 

for (x = 0; x < 5; ++x) counter(); 

} 

counter() 

{ 

static int count = 1; 
printf("%d", ++count); 

} 
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The output from this example would be: 

2 3 4 5 6 


Each time we call counter(), the variable count is incremented and printed out. If we hadn't declared 
count as a static variable, the output would have been a string of twos. Do you see why? When a 
static variable is initialized as we did in counterQ, it receives its initial value the first time we call the 
function. Thereafter, the declaration and initialization is ignored. This is only logical, since what good 
would a static variable be if it was reinitialized each time we called the function? 

By not declaring count as static, by default, it becomes automatic. Each time we call the function, it 
gets set to 1, and then it's incremented and printed. This gives us that string of twos. 

One last note on static variables. An interesting variation of this class can be created by defining it 
outside any function. This type of variable is called external static. This class varies from regular 
external variables, in that it can be accessed only within the file where it appears and only in 
functions following its declaration. 

The last class we need to discuss are register variables. They're defined 
like this: 


register int number; 


When we declare a register variable, we're requesting that the value be stored in one of the the 
computers registers where processing is much quicker. Notice I used the word requesting. If there's 
no register free in which to store our variable, it becomes an automatic variable. 

Hip, Hip Array! 

We took a brief look at arrays when we wrote our sort program a couple of chapters ago. Now we're 
going to dig a little deeper. 

First, let's tackle Listing 2. Suppose you're selling a peculiar product called a whamble (a what?) in 
your small business. At the end of the week, you want to write a quick and dirty program that'll print 
the number of units sold that week. Listing 2 is just such a program. When you run it, your output 
should look like this: 


Sales 

for 

day 

1 

5 

Sales 

for 

day 

2 

7 

Sales 

for 

day 

3 

2 

Sales 

for 

day 

4 

10 

Sales 

for 

day 

5 

7 

Sales 

for 

day 

6 

1 

Sales 

for 

day 

7 

6 

Total 

sales: 

38 



The first thing we must do in this program is initialize an array. In our sorting program, we didn't 
worry about that. All we did was declare the array, and then fill it, later in the program, with the 
numbers the user input. Sometimes, though, you'll need to have the array data stored and ready to 
process at run time. Line 7 of Listing 2 shows you how to do this. 
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To initialize an array as part of its declaration, the array name is followed by an equal sign, which, in 
turn, is followed by the elements of the array, separated by commas and placed betweenbrackets. 
Here are some more examples: 

int numbers[] = { 1, 2, 4 }; 

int numbers[3] = { 1, 2, 4 }; 

float numbers[] = { 1.1, 2.2, 4.4 }; 


The first is just like the declaration on Line 7, and the second example is, in this case, functionally the 
same as the first. However, it does present potential difficulties and can create some hard to locate 
errors. 

For instance, in the first example the compiler automatically makes the array size the same as the 
number of values that follow. In the second example we're telling the compiler that, no matter what, 
we want a three-element array. 

Here's an odd one: 


int numbers[4] —{1,2}; 


What do you suppose happens here? Well, the compiler sets aside an array containing four 
elements, then looks to see what we've got between the brackets. The first value goes into the first 
element, the second into the second. After that, if it's an external or static array, the remaining 
elements are set to 0. Otherwise, whatever garbage happens to be in those locations stays there. 
Trouble, for sure. 

Here's another problem maker: 

int numbers[2] = { 1, 2, 4 }; 


There's no way you're going to get away with this. Your compiler is sure to present you with some 
snide comments on your programming skills - and they'll be well deserved. You can't get three data 
items into a two-element array. 

Continuing with Listing 2, after we've initialized our array, the program uses a for loop to access each 
element, add it to the total and print it out. Except for a little nuance with the way we've initialized 
the for loop, you've seen all this before. Just remember that an array starts at element 0. 

Now, how about that nuance I mentioned? Look at Line 14. I hope you remember about for loops. 
The first expression in the parentheses is the initialization, the second is the loop control, and the 
third is the loop's step value. 

In this example, we've taken the opportunity to initialize not only the loop variable, but the 
accumulator total as well. This is a handy way to set variables used within a loop to their starting 
values. 

Line 15 offers a new assignment operator for your inspection, one that's quite similar to the 
increment and decrement operators. Line 15 does the same work as this line of code: 

total = total + weekfi]; 
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The right side of the expression is added to the left. 

Another Dimension 

C is also capable of handling multi-dimensional arrays. You can think of these as arrays of arrays. 
Listing 3 illustrates how to handle them. 

The declaration is similar to that of a one-dimensional array, except we've added another set of 
brackets to tell the compiler how we would like the array set up. Look at Line 8. Here we're declaring 
an array with two sets of seven elements. You can think of this as a matrix with two rows and seven 
columns. 

When we initialize the array, each row of data is placed within its own set of braces. The rows, just 
like the data within, are separated by a comma. Finally, the entire array is enclosed with another set 
of braces. This tells the compiler how we want each element placed. Take a look at this: 

int a [ 2 ] [ 3 ] = { { 1, 2 }, { 3, 4, 5 } } ; 

Here, we've declared an array which contains two arrays of three elements each. But wait a minute! 
In our initialization, we're missing a data element for the first subarray. How's this going to work out? 
Is the first element of the second row going to end up as the third element in the first? 

Nope. The 1 will be placed in the first element of the first row. The 2 will go in the second. The third 
element of the first row will be initialized to 0. (Remember that rule about external data?) The 
second row will be initialized just the way we want it. No mix-ups. 

To tell you the truth, you don't need all those extra braces. We could've initialized weeks[][] by 
placing all the data between one set of brackets, like this: 

{ 3,6,7,4,3, 8, 9,5,3,7, 9,3,2,6 } 


The array will still function properly, but it's much harder to see how the data's divided up — and 
we've left ourselves open for possible errors. If we should accidentally (or deliberately, if you happen 
to enjoy that sort of thing) leave out one of the data elements, the compiler will no longer sort it out 
for us, making sure everything gets into its proper location. It'll assign each element consecutively 
until it runs out of data, and then initialize the rest to 0. Our program is then sure to act peculiarly. 
This type of error can be extremely difficult to locate. 

Whambles For Sale 

Okay, enough talk. Compile Listing 3. A program run looks like this: 
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Sales 

for 

day 

1 

3 

Sales 

for 

day 

2 

6 

Sales 

for 

day 

3 

7 

Sales 

for 

day 

4 

4 

Sales 

for 

day 

5 

3 

Sales 

for 

day 

6 

8 

Sales 

for 

day 

7 

9 

Total 

sales: L . 

0 


Sales 

for 

day 

1 

5 

Sales 

for 

day 

2 

3 

Sales 

for 

day 

3 

7 

Sales 

for 

day 

4 

9 

Sales 

for 

day 

5 

3 

Sales 

for 

day 

6 

2 

Sales 

for 

day 

7 

6 

Total 

sales: 35 


Total 

sales for 

month 


Two weeks; what a short month. Yes, I know there are usually four weeks in a month. The output 
was limited, to fit the screen. 

This program is an example of indexing a two-dimensional array. Lines 17 and 18 set up nested for 
loops. The outer loop handles the indexing of the weeks; the inner loop indexes days. 

The day loop is performed seven times for each iteration of the week loop. Line 19 shows how all this 
relates to our array. The first subscript in weeks[w][d] refers to each row of data (weeks). The second 
is the columns, or days. The first time we get to Line 19, w and d both equal 0, so we're looking at 
weeks[0][0] -- that is, the data in row 0 and column 0. If we look at the array initialization, we see 
that this is the value 3. 

The day's total sales are printed, and then the inner loop is repeated, incrementing d and advancing 
us to row 0's next element. Looking at the data, we see that weeks[0][l] equals 6. This loop repeats 
until d is no longer less than 7. At that point we drop through to Line 22 and print the total for the 
week, as well as add to our monthly total (in the next line). 

When the program returns to the outer loop, w is incremented, and we re-enter the inner loop, 
resetting d to 0. Now we're referencing weeks[l][0], row 1 and column 0, or the value 5. The inner 
loop continues through row 1 just as it did with row 0. 

When we return to the outer loop, the value of w is incremented again, and thus is no longer less 
than 2. The looping is completed, and program execution continues at Line 32 where the monthly 
total is printed. 

That's it for this chapter. Sit back and relax. Put your feet up, massage your temples to get rid of that 
thundering headache. (Arrays are like that; yeah, they are.) Next chapter, we'll start developing our 
own input routines, so we won't be at the mercy of such functions as scanf(). In the meantime, fool 
around a bit more with arrays. They're neat little critters. 


Program Listing #1 


j •k-k-k'k-k-k-k-k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k 

* C-MANSHIP * 

* Chapter 5 * 

* Listing 1 - Developed with Megamax C * 

•k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k/ 

#include <stdio.h> 

#include <osbind.h> 

#define TRUE 1 
#define FALSE 0 
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/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 


* MAIN PROGRAM 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkj 


main () { 

int 


num, 

guess, 
win, 
turns, 
play; 


/* Number to guess. */ 

/* Player's guess. */ 

/* Game end flag. */ 

/* Number of guesses. */ 
/* Repeat game flag. */ 


play = TRUE; 
while ( play ) { 

turns = 0; 
win = FALSE; 
num = get num (); 
while ( !win ) { 

++turns; 

guess = get_guess (); 

win = check guess ( num, guess ); 

} 

printf ( "It took you %d turns. \n\n", turns ); 
play = play_again (); 

} 

} 


jkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* get_num() 

k 

* Returns a random number from 1 to 100. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

int get__num () 

{ 

int n; 


n = (int) Random (); 
n = abs(n) % 99 + 1; 

return ( n ); 

} 

jkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* get_guess () 

k 

* Retrieve a number from 1 to 100 from the 

* keyboard. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

int get_guess () 

{ 

int g; 
g = 0; 

while ( g<l || g>100 ) { 

printf ( "Enter a number from 1 to 100: " ); 
scanf ( "%d", &g ); 
printf ( "\n\n" ); 

} 

return ( g ); 

} 

jkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* check_guess() 

k 
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* Compare the player's guess with the random 

* number, and print the appropriate message. The 

* input to the function is the original number 

* and the player's guess. This function returns 

* a value of TRUE if the number has been guessed, 

* and FALSE otherwise. 

■k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k'k-k'k-k'k-k'k-k'k-k-k-k-k-k'k'k-k'k-k-k-k-k-k'k-k-k-k'k-k-k-k'kj 

int check_guess ( num, guess ) 
int num, guess; 

{ 

int wn = FALSE; 

if ( guess < num ) 

printf ( "Too low\n\n" ); 
else if ( guess > num ) 

printf ( "Too high\n\n" ); 

else { 

printf ( "You guessed it!\n" ); 
wn = TRUE; 

} 

return ( wn ); 

} 
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/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* play_again() 

k 

* Asks the player if he wishes to play again and 

* returns a value of TRUE if he does or FALSE if 

* he doesn't. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkj 

int play_again () 

{ 

int ch, p; 

P = -1; 

ch = getchar (); 

while ( ( p!=TRUE ) && ( p!=FALSE ) ) { 

printf( "Play again? " ); 

if ( ( ch=getchar () ) == 'y' | | ch == 'Y' ) 

p = TRUE; 

else if ( ch == 'n' || ch == 'N' ) 

p = FALSE; 

} 

printf ( "\n\n" ); 
return ( p ); 

} 


Program Listing #2 

Jkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 


* C-MANSHIP * 

* Chapter 5 * 

* Listing 2 - Developed with Megamax C * 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkj 


#include <stdio.h> 
int week[] = { 5, 7, 
main () 

{ 

int i, 

total, 
ch; 


2, 10, 7, 1, 6 } ; 


/* Loop variable. */ 

/* Sum of weekly sales. */ 
/* Character storage. */ 


for ( i=0, total=0; i<7; i++ ) { 

total += week[i]; 

printf ( "Sales for day %d: %d\n", i+1, week[i] ); 

} 

printf ( "\n" ); 

printf ( "Total sales: %d", total ); 
ch = getchar (); 

} 
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Program Listing #3 

j •k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k 


* C-MANSHIP * 

* Chapter 5 * 

* Listing 3 - Developed with Megamax C * 

•k-k'k-k'k-k-k-k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k^ 


#include <stdio.h> 
int weeks[2][7] = { { 3 
{ 5, 3, 7, 9, 3, 2, 6 } 
main () 

{ 

int w, 

d, 

mtot, 

wtot, 

ch; 


6, 7, 4, 3, 8, 9 }, 

} ; 


/* Loop variable--weeks. */ 
/* Loop variable--days. */ 
/* Weekly total. */ 

/* Monthly total. */ 

/* Character storage. */ 


for ( w=0, mtot=0; w<2; w++ ) { 

for ( d=0, wtot=0; d<7; d++ ) { 

wtot += weeks[w][d]; 

printf ( "Sales for day %d: %d\n", d+1, weeks[w][d]); 

} 

printf ( "\n" ); 

printf( "Sales for week %d: %d\n\n", w+1, wtot ); 
mtot += wtot; 

} 

printf ( "\n\n" ); 

printf ( "Total sales for month: %d\n", mtot ); 
ch = getchar (); 
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CHAPTER 6 - FILE HANDLING AND CUSTOM INPUT ROUTINES 


This chapter, as I promised, we'll get busy designing our own input routines. We're no longer going to 
suffer with the limitations of such library routines as scanf(). And, to add a little spice to the 
proceedings, how about learning a little about disk file handling? 

Listing 1 is this chapter's sample program. Type it in and compile it. The program is an embarrassingly 
simple text editor. When you run it, you'll be asked for a filename. If the filename you enter already 
exists on the disk, you'll be asked if you wish to delete the file. If you answer Y, the file will be deleted 
and a new one created. Any other response will let you enter a different filename. 

The text is entered one line at a time. When you reach the right margin (medium resolution), press 
Return for the next line. If you try to type beyond the right margin, the program will automatically 
terminate the line. You'd be wise to avoid this, since the last character you typed will be lost. You 
should also check each line for typos before pressing Return. There are no editing features (except 
backspace) in this program. 

Press CTRL-Z (that's the Control key and the Z, simultaneously) to close the file. You may then print or 
view the text from the GEM desktop, by double-clicking the file you created. 

The Innards 

There's nothing fancy going on in this program — just a couple of new functions to learn and, most 
importantly, a new method for accepting input. No more scanf(). From now on, every key will be 
under our control. First take a look at the #define statements at the top of the program. MAX is the 
length limit for each line. RETURN, BACKSP and CTRL_Z are the ASCII values for some of the keys we'll 
be checking for in our input routine. Don't pay any attention to NOFILE right now; we'll get to that 
later. Notice, also, that here we're declaring an integer variable, code. Since it's defined outside of 
any function, it's a global variable — one we can access from anywhere in the program. 

If you look at the function main(), you'll see that we've declared two character arrays, filename)] and 
text[]. The first will hold the name of the disk file we'll be working with; the second will store each 
line of text as it's typed. 

The body of main() consists of only three statements. These represent the activities we must 
complete to create our text file. The function call at Line 27 will open our file; Line 28 will allow us to 
enter our text; and Line 29 will close the file. And you thought programming in C would be tough. 
Only three function calls! 

Well, if you've been following the lessons carefully, you're aware that main() is only the general 
outline of the program; the trickier stuff is still to follow. But don't get panicky. Handling files in C is a 
snap, not much tougher than in BASIC. 

Doing it Our Way 

In the past, we've been at the mercy of C's built-in I/O functions. Actually, these functions are not 
part of C at all. They're small routines other programmers have put together, then gathered into a 
library for our convenience. It's nice to have these functions lying around in case we need them, but 
there's always a price to pay when we take a shortcut. The price is a loss of flexibility. 

If we use library functions like scanf(), we have to follow the rules somebody else made up. 
Frequently, these rules will be at odds with what we wish to accomplish. The solution? Write our 
own input routines, using our own set of rules. 

This might sound a bit scary, but, depending on how fancy we want to get, there's really nothing to it. 
For our simple text editor, we don't need to convert strings to decimal values or perform any of the 
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other tricks a complete input routine must be capable of. All we have to do is let the user type in one 
character after another, terminating his line with a Return. 

In Listing 1, down near the bottom, you'll see a function called get_str(). This is our input routine. The 
body of the function is only 12 lines long (not counting comments) — a veritable piece of cake. As you 
can see by the function declaration, get_str() receives one argument from the calling function: the 
address of the character array where we wish the string stored. 

We start off at Line 124 by initializing n, our array index, to 0. Then, in order to slip neatly into the 
while loop at Line 130, we get our first character from the console (the ASCII value), utilizing one of 
the GEMDOS functions, conin. Note that this function is not a part of C; rather it is a call to the ST's 
operating system. If we were to try to port this program to another system, we would have to 
replace the call to conin with the new machine's equivalent function. 

What's all this GEMDOS stuff? The ST's operating system (OS) is called TOS, right? It even says so 
right there on my old boot disk. T-O-S. Well, TOS is an incredibly complex animal, made up of two 
main parts: the BIOS (Basic Input/Output System) and GEMDOS (actually, there's also the XBIOS, but 
that's just an extension of the BIOS). The BIOS is the lowest level of the OS, and handles all the ST's 
primary input/output functions. 

You can think of the BIOS as the software that runs the hardware, the meat in the sandwich between 
GEMDOS and all those data buses and microchips. GEMDOS provides the programmer with 
convenient access to the BIOS. 

GEMDOS supplies over fifty functions, of which conin is function number one. In upcoming chapters, 
we'll be exploring GEMDOS in more depth. 

Notice that in Lines 130 and 154 we're calling a function named Cconin(). This is the function that will 
get us those keystrokes. What happened to conin? One of the files we included at the beginning of 
our program was OSBIND.H. If you get a print out of this file, you'll see that it's nothing more than a 
long list of #define statements. About half-way down, you'll see this statement: 

#define Cconin() gemdos(Oxl) 

You should be familiar with how the #define statement works. Wherever the compiler sees the word 
Cconin() in our source code, it'll substitute gemdos(Oxl). The word conin is just a name someone 
came up with for GEMDOS function 1. 

To access this function we must use the call gemdos(Oxl). (Don't let the "Ox" in front of the function 
number throw you off. It just means the number should be interpreted as hexadecimal, rather than 
decimal.) Using names like Cconin() for GEMDOS functions reminds us of what the function does. We 
could have put the call gemdos(Oxl) directly into our source code and not bothered with including 
OSBIND.H. 

A Bit of Construction 

The function get_str() begins on Line 119. All this function does is get characters one by one and 
place them in successive bytes of the character array. There's a small complication, however. Several 
keys have special functions. For instance, Return ends a line, CTRL-Z closes the file, and the 
backspace key allows the user to correct mistakes. We'll have to check for these keys as the user 
types. 

At Line 124, we initialize the array index n. We then get our first character and slip into the while 
loop that follows. The loop checks for a Return or a CTRL-Z and makes sure we haven't gone past the 
end of our array. 
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Line 133 checks for a Backspace. If we didn't get one, the character that was typed is added to our 
array, text[]. Line 134 accomplishes this, as well as incrementing the index n (notice that n is being 
post-incremented; that is, the array is first indexed by n, then n is incremented). Program execution 
then drops down to Line 151, where we get our next keystroke. 

If a Backspace is entered, and we have at least one character in the array, we replace the last 
character typed with a null (Line 141). We also have to adjust the screen display. This is done in Lines 
144 and 147. Since the cursor was moved on top of the last character in the line when the Backspace 
was typed, all we have to do is print a space (Line 143), then place the cursor back in its proper 
position by printing a Backspace to the screen (Line 147). To print these characters to the screen, 
we're using Cconin()'s counterpart, CconoutQ, which writes a single character to the screen. 

Sooner or later, the user will type a Return to end a line or a CTRL-Z to close the file, at which point 
we exit get_str(). 

Disk Files 

Fortunately for us struggling programmers, there are many functions for handling disk files. Four of 
these functions concern us at the moment. They are: open(), creat(), write() and close(). 

The function open() opens a file already in existence. It requires two arguments: the address of the 
filename and the type of access required. The latter may be one of three values: 0 (read only), 1 
(write only), or 2 (read and write). We can add 8192 to any of these three values in order to open the 
file in "untranslated" binary mode. Untranslated means that the data is interpreted as a continual 
stream of bytes, rather than lines ending with carriage returns and line feeds. The difference 
between the two modes can be critical, depending on our usage. 

The function open() also returns a value. If it encounters an error and fails to open the file (the file 
didn't exist), it'll return a -1. Now you know why I defined NOFILE at the top of the program equal to 
this value. If the file is opened successfully, the function will return a file descriptor. We'll use this 
number whenever we wish to access the file. 

The function creat() starts a new file and also requires two arguments: the address of the filename 
and a flag value. The flag must either be 0 or 8192, the latter meaning we want the file created for 
use in the untranslated mode. If, when we call this function, the file we wish to start already exists on 
the disk, the file's pointer will be moved to the beginning of the file, effectively deleting it. Just like 
open(), a -1 is returned in the case of an error, or a file descriptor if successful. 

The function write() saves data to a file. It requires three arguments: the file descriptor, the buffer 
starting address (where the data is stored) and the number of bytes to write. A successful write will 
return a value equal to the number of bytes actually written. Otherwise, a -1, indicating an error, will 
be returned. 

The function close() closes a file and requires the file descriptor as its argument. If the file is closed 
successfully, a 0 will be returned. An unsuccessful close, meaning we used an unknown file 
descriptor, will yield a -1. 

Starting Our File 

Look at the function start_file() in Listing 1. It receives one argument from main(), the address of the 
character array, filename[]. This will be the first argument for open() and creat(). The variable file will 
hold our file descriptor and is initialized to -1 (Line 47), so we can get into the while loop that follows. 
As long as file is equal to -1, this loop will repeat, prompting the user for a filename until a file is 
successfully created. 
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Within the loop, we print a prompt, then call get_str() to allow the user to input the filename. At Line 
57, if the file descriptor we receive from open() equals -1, we know the file doesn't already exist, so 
we go ahead and create it (Line 60). 

If we get a value other than -1, it means there's already a file by that name on the disk, and the 
program continues at Line 67. Here we reinitialize file to -1, then ask the user if he wants to delete 
the file. If he answers yes, the old file becomes the new file (Line 73), otherwise the loop repeats, 
asking for another filename. 

Writing Our File 

Now let's study the function get_text() in Listing 1. You should have little difficulty figuring it out. 

First we prompt the user to input his text; then we initialize code (the global variable that'll contain 
the ASCII value of each keystroke) to 0. We then call get_str() to get the first line of text. This function 
will return the number of characters typed. 

In Lines 103 and 104, a line feed and a null are added to the string (otherwise, when we try to print 
the file, the lines will be concatenated). Finally, in Line 107, we write the text to disk. We repeat the 
while loop until code equals 26 (a CTRL-Z), at which point the function terminates, and the file is 
closed at Line 29. 

Simple, but Cute 

So there you have it. There's not much to this program, but it can be useful for creating small 
README.DOC files for your disks. It's certainly easier than loading up a full-fledged word processor 
when all you want to do is type in a couple of lines. Most importantly, we now know how to save 
data to disk and how to get input from the user without relying on such undependable functions as 
scanf(). 


Program Listing #1 

/■k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k 

* C-MANSHIP * 

* Chapter 5 * 

* Listing 1 - Developed with Megamax C * 

•k-k-k-k-k-k-k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k-k'k-k'k-k-k-k-k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k^ 

#include <stdio.h> 

#include <osbind.h> 

#define TRUE 1 
#define FALSE 0 


/•k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k 


* MAIN PROGRAM 

■k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-kj 

main () 


int num, 

guess, 
win, 
turns, 
play; 


/* Number to guess. */ 

/* Player's guess. */ 

/* Game end flag. */ 

/* Number of guesses. */ 
/* Repeat game flag. */ 
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play = TRUE; 
while ( play ) { 

turns = 0; 
win = FALSE; 
num = get num (); 
while ( !win ) { 

t+turns; 

guess = get_guess (); 

win = check guess ( num, guess ); 

} 

printf ( "It took you %d turns. \n\n", turns ); 
play = play^again (); 

} 

} 

/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* get_num() 

k 

* Returns a random number from 1 to 100. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

int get num () 

{ 

int n; 

n = (int) Random (); 
n = abs(n) % 99 + 1; 

return ( n ); 

} 

j •k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k 

* get_guess () 

■k 

* Retrieve a number from 1 to 100 from the 

* keyboard. 

■kk-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-kj 

int get_guess () 

{ 

int g; 
g = 0; 

while ( g<l || g>100 ) { 

printf ( "Enter a number from 1 to 100: " ); 
scanf ( "%d", &g ); 
printf ( "\n\n" ); 

} 

return ( g ); 

} 
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! •kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* check_guess() 

k 

* Compare the player's guess with the random 

* number, and print the appropriate message. The 

* input to the function is the original number 

* and the player's guess. This function returns 

* a value of TRUE if the number has been guessed, 

* and FALSE otherwise. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

int check_guess ( num, guess ) 
int num, guess; 

{ 

int wn = FALSE; 

if ( guess < num ) 

printf ( "Too low\n\n" ); 
else if ( guess > num ) 

printf ( "Too high\n\n" ); 

else { 

printf ( "You guessed it!\n" ); 
wn = TRUE; 

} 

return ( wn ); 

} 

j •kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* play_again() 

* Asks the player if he wishes to play again and 

* returns a value of TRUE if he does or FALSE if 

* he doesn't. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk J 

int play_again () 

{ 

int ch, p; 

P = -l; 

ch = getchar (); 

while ( ( p!=TRUE ) && ( p!=FALSE ) ) { 

printf( "Play again? " ); 

if ( ( ch=getchar () ) == 'y' | | ch == 'Y') 

p = TRUE; 

else if ( ch == 'n' || ch == 'N' ) 

p = FALSE; 

} 

printf ( "\n\n" ); 
return ( p ); 

} 
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Program Listing #2 

j ■kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 


* C-MANSHIP * 

* Chapter 5 * 

* Listing 2 - Developed with Megamax C * 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 


#include 

<stdio.h> 


int week[ 

] = { 5, 7, 

2, 10 

main () 



{ 



int 

1 r 

/* 


total, 

/* 


ch; 

/* 


7, 1, 6 } ; 

Loop variable. */ 

Sum of weekly sales. */ 
Character storage. */ 


for ( i=0, total=0; i<7; i++ ) { 

total += week[i]; 

printf ( "Sales for day %d: %d\n", i+1, week[i] ); 

} 

printf ( "\n" ); 

printf ( "Total sales: %d", total ); 
ch = getchar (); 

} 


Program Listing #3 

j kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk J 

/* C-MANSHIP */ 

/* Chapter 6 */ 

/* Listing 1 - Developed with Megamax C */ 

J •k'k-k'k-k'k-k'k-k'k-k'k-k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k J 

#include <stdio.h> 

#include <osbind.h> 

#define RETURN 13 
#define BACKSP 8 
#define MAX 78 
#define NOFILE -1 
#define CTRL_Z 26 

int code; 

J-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k 

* MAIN PROGRAM 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkJ 

main () 

{ 

char filename[15], /* Filename for text file. */ 
text[MAX]; /* Text entered by user. */ 
int file; /* File ID. */ 

file = start file ( filename ); 
get_text ( file, text ); 
close ( file ); 

} 
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/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* start_file () 

k 

* Gets the filename from the user, and then opens the 

* file. The input to the function is the address of 

* storage for the filename. The function's output is 

* the open file's file ID. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkj 

start file ( filename ) 

char filename[]; 

{ 

int file, /* File ID. */ 

ch; /* Character storage. */ 

/* Initialize file ID to error condition. */ 
file = NOFILE; 

/* Continue trying to open a file until successful. */ 
while (file == NOFILE) { 

/* Get filename from user. */ 
printf ( "Filename: \n" ); 
get_str ( filename ); 

/* Check if file already exists. */ 

if ( ( file = open(filename,2) ) == NOFILE ) 

/* If it doesn't exist, create it. */ 
file = creat ( filename, 0 ); 

/* The file the user wants to open already exists. */ 
else { 


} 


/* Reset file ID to error condition in case user */ 
/* doesn't want to delete already existing file. */ 
file = NOFILE; 


/* Find out if user wants to delete the existing 
/* file and create a new one. */ 
printf ( "File already exists! Delete it? " ); 
if ( (ch = getchar() ) == 'Y' || ch == 'y' ) 

file = creat ( filename, 0 ); 


} 

printf ( "\n" ); 
return ( file ); 


*/ 


Jkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* get_text () 

k 

* Get the text to be stored in the file from the user. 

* The inputs to the function are the file's ID and 

* the address of string storage. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkj 

get_text ( file, text ) 
int file; 
char text [ ]; 

{ 

int num char; /* Number of characters in string. */ 

printf( "Type your message:\n\n" ); 
code = 0; 
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/* Get text from keyboard until user wants to exit. */ 
while ( code != CTRL Z ) { 

/* Get a string of text. */ 
num_char = get_str ( text ); 

/* Add a LF and a null to the string. */ 
text[num_char++] = ' \n'; 
text[num^char] = '\0' ; 

/* Save the text string to the file. */ 
write ( file, text, num char ); 

} 

} 

/■k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k'k-k'k-k'k-k'k-k'k-k'k-k'k-k 

* get_str () 

•k 

* Gets each of the strings that make up the text file. 

* The input is the address of the string storage. The 

* output is the number of characters in the string. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

get_str ( text ) 
char text[]; 

{ 

int n; /* Character count. */ 
n = 0 ; 

/* Get character code from keyboard. */ 
code = Cconin(); 

/* Check if end of string or end of text. */ 
while ( code != RETURN && code != CTRL_Z && n <= MAX ) { 

/* Add character to string if not a backspace. */ 
if ( code != BACKSP ) { 

text[n++] = code; 

} 

/* Handle backspace character. */ 
else if ( n > 0 ) { 

/* Shorten string by one character. */ 
text[--n] = '\0' ; 

/* Erase character on screen. */ 

Cconout ( ' ' ); 

/* Move cursor back one space. */ 

Cconout ( BACKSP ); 

} 

/* Get next character code. */ 
code = Cconin (); 

} 

printf ( "\n" ); 
return ( n ); 

} 
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CHAPTER 7 - POINTERS AND MACROS 

Handling pointers can be confusing at times, though the basic concept is quite simple. Believe it or 
not, we've been using pointers for several chapters now, whenever we referred to an array name. 

What exactly is a pointer? Simply put, it's a variable containing the 

address of a data item we wish to access. For example, look at this line of code: 

pointer = Svar; 

After this line has been executed, pointer will contain the address of var, or to say it another way, 
pointer will point to that section of memory where the value of var is stored. 

So, what's all the hoo-ha? Why not use the & operator and be done with all this nonsense? Because 
there's a subtle difference between pointer and &var. The first is a variable; the second is a constant. 
Still not impressed? Okay, let me ask you a question: what makes variables so handy? Give up? We 
can perform mathematical procedures on variables; not so with constants. 

Another advantage to pointers is that, when declared properly, they're much "smarter" than 
constants or run-of-the-mill variables. We'll see why in a minute. 

A Point of Declaration 

In order for us to use a pointer, the compiler needs some information, namely the type of data the 
pointer points to. We supply this information in the pointer's declaration: 

int *pl; 
char *p2; 
float *p3; 

The first example above tells the compiler that we want a pointer to an integer value. The second 
sets up a pointer to character data. The third points our way to floating point information. 

Each of these data types (as well as others) is stored in a special way in memory. A pointer to integer 
won't function as we expect if we try to use it on character data. The "*" before the name identifies 
the variable as a pointer and requests "special handling" from the compiler. Don't confuse this 
symbol with the multiplication operator. 

Once we've declared our pointer, we have to assign it a value. We want it to point to something, 
don't we? We assign an address to a pointer in exactly as we would to any other variable. Take a look 
at this segment of code: 

int var, arrayjlO]; 
int *pl, *p2, *p3; 

pi = Svar; 
p2 = array; 
p3 = Sarray [5]; 

First, we've declared an integer variable and an integer array. Following that are the declarations for 
three pointers to integer. After declaration, these pointers are still useless to us. We have to assign 
them values — addresses to point to. 

In the first case, pi is assigned the address of var (or &var). Don't forget the ampersand; without it, 
we'd be assigning the value of var, not its address. In the second assignment, p2 gets the address of 
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the first element of the array array[]. What? No ampersand? Don't tell me you've forgotten already! 
An array name is an address. 

Ah, but what about the third assignment in our example? There's that address operator. No mistake 
here. Once we add the brackets to the array name, we're referring to the contents of an element of 
the array, not its address. Just remember: the only time we don't need the address operator is when 
we're doing our assignment with an array name. The following two lines do exactly the same thing: 

pi = array; 
pi = Sarray[0]; 

Putting Them to Work 

Okay, now we've got our pointers declared and assigned addresses. Now what? There are several 
operations we can perform with pointers, including: assignment, getting the address, getting a value, 
and incrementing or decrementing. 

The first, assignment, we've already learned about. The second, getting the address, is nothing new, 
either. To get the address of a pointer — the place in memory where the pointer itself is stored -- 
place the address operator in front of the pointer name: 

adrpl = &pl; 

A more useful operation is getting the value the pointer is pointing to: 

var = 5; 
pi = Svar; 
z = *pl; 

In the above example, z becomes equal to var. How? Our pointer, pi, is assigned the address of the 
variable var. The third line is read "z gets the contents of the address pointed to by pi." The asterisk 
is referred to as an "indirection operator," since it allows us to access data indirectly. 

Of course, this is a pretty silly example. It would have been more efficient to directly assign the value 
of var to z (z = var), but there are times when we can't get at variables in the conventional way. 
Remember, C passes arguments between functions by value, not address. 

Take, for instance, our bubble sort program from a couple of chapters ago. What if, instead of using 
an array, we had three integer variables we wanted to sort, then pass back to the calling function? 
The following lines show a function call and the first two lines of the function. Will it work? 


sort(x. 

y, z); 

sort(a. 

b, c) 

int a. 

b, c; 


Think about it for a minute. The three arguments passed to the sort function are placed in the three 
automatic variables a, b and c. No problem there, so we go ahead and sort the three values (code not 
shown), putting y into x, and z into y, and x into z - or whatever's necessary to complete the sort. 
Hurray! We did it. 

Wrong. 

We forgot one tiny detail. We now have to pass all three values back to the calling function. Any 
suggestions? The return() statement will allow only one argument. Looks like we're stuck. 
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What did we do wrong? Why is C being so obstinate? Shall we forget the whole thing and go back to 
BASIC? Nope. 

The solution to our dilemma is (drumroll, please): pointers. 

Let's change our function call to this: 

sort(&x, &y, &z); 

We're still passing our arguments to automatic variables, but now those variables will contain the 
addresses of the original three. And, to make things as efficient and elegant as possible, we're going 
to make those automatic variables pointers. The first two lines of our function will look like this: 

sort(pi, p2, p3) 
int *pl, *p2, *p3; 

Now we have access to the variables from the calling function. We can switch them around any way 
we want, using code similar to this: 

save = *pl; 

*pl = *p2; 

*p2 = *p3; 

*p3 = save; 

In English, the above reads: "save gets the contents of the address pointed to by pi; the contents of 
the address pointed to by p2 gets stored in the location pointed to by pi"; and so on. What we're 
actually doing is this: 

save = x; 
x = y; 
y = z; 
z = s ave; 

Once we've got the variables the way we want them, we exit the function. We don't have to return 
any values now; we've done all our work on the variables themselves. 

Incrementing and Decrementing 

I stated earlier that pointers were much smarter than conventional variables. One reason is that 
they're mathematical whizzes. When we perform addition or subtraction on a pointer, the compiler 
does a lot of the work for us, taking into account the data type it's pointing to and the way that data 
is stored in memory. 

For instance, if we add 1 to an integer pointer, we don't end up with an address one byte higher in 
memory; we actually move forward two bytes. The compiler knows that integers are two-byte 
animals, and if we're going to end up with a usable address, the pointer we're incrementing had 
better end up pointing to the beginning of the next integer. 

Now let's have a short quiz. A character array has a beginning address of 73455. A pointer to 
character, pi, has been initialized to the starting address of the array. What address will we get if we 
increment the pointer? Answer: 73456. Character data requires one byte of storage for each element 
in the array. Adding 1 to the pointer yields the address of the next element in the array. In this case, 
the next element is one byte higher in memory. 

The Proof 

Now's a good time to dig into Listing 1. Type it in, compile and run it. The output should look 
something like this: 
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+ 0 

pl=71926 

&pl=72910 

*pl=65 

+ 0 

pl=71926 

&pl=72910 

*pl=65 

+1 

pl=71927 

&pl=72910 

*pl = 6 6 

+2 

pl=71928 

&pl=72910 

*pl=67 

+ 0 

p2=71930 

&pl=72914 

*pl=10 

+ 1 

p2=71932 

&pl=72914 

*pl=ll 

+2 

p2=71934 

&pl=72914 

*pl=12 

Press any key 



The table this program prints sums up everything we've discussed about pointers. Take a look at the 
first line of the table. Using what you've just learned, what's the address of the letter A (65) in the 
character array arrayl[]? If you answered 71926, then you probably have a good basic understanding 
of how pointers work. 

For those of you who are still confused, don't fret. It'll sink in as you get accustomed to using 
pointers. Let's go through the program and see what's going on. 

Lines 9 and 10 declare the arrays and pointers, as well as initializing the arrays. Line 16 puts the 
address of the first element of arrayl[] into the character pointer pi. Line 17 prints out the four 
values in our table: the amount added to the pointer, the contents of the pointer, the address of the 
pointer, and the contents of the address the pointer's pointing to. The first line of the table will be 
printed again when we get into the loop at Line 18. The reason for this is to show you that setting the 
pointer with the array name is equivalent to setting it with the address operator preceding an array 
element. In this case, we're comparing arrayl with &arrayl[0]. 

Lines 18 through 21 move the pointer through arrayl[], using the address operator. Each pass 
through the loop prints one line of our table. Lines 23 through 26 accomplish the same thing, only 
now we're cycling through an array of integers and incrementing the pointer itself, rather than 
assigning a new address to it with the address operator. 

A Glimpse of Macros 

Notice that, in Listing 1, we've used printf() three times, in almost exactly the same way. In fact, the 
only difference between them is the name of the pointer we're working with. If the programmer's 
voice within you is screaming that it's stupid to code the same thing three times, then listen to it. It's 
right. C provides us with a handy technique to avoid this type of redundant code. The technique 
involves the use of macros. 

Just as was true with pointers, you've already been exposed to macros -- though you were probably 
unaware of it. Every time we use the #define statement, we're setting up a macro. We've done this 
dozens of times, but only in the simplest fashion. Macros can be quite complex and are powerful 
programming aids. 

Listing 2 is a modification of Listing 1. Here, each occurrence of the printf() call has been replaced 
with a macro call. The macro itself is defined in Line 9. Any legal variable name can be used as a 
macro name. 

See the parentheses? This macro contains an argument that will be passed when the macro is 
expanded (when the substitution string replaces the macro's name in the code). In our example, the 
argument will be the pointer name to be used in the table. 

Of course, just placing the argument in the macro name isn't enough. We've got to tell the macro 
where we want the argument used in the expansion. In our example, every Z in the replacement 
string will be replaced by the argument supplied when the macro is called. 
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Lines 19, 23 and 27 show the macro calls. In Lines 19 and 23, pi will be substituted into the 
replacement string. In Line 27, p2 will be substituted. 

One interesting note: When I first wrote the program shown in Listing 2, I was using the C compiler 
that was supplied with the Atari Developer's Kit (Alcyon C). That compiler allows the programmer to 
place a macro argument within a string, so that the output of Listing 2 could be made identical to the 
output of Listing 1. Unfortunately, Megamax C doesn't allow macro arguments to be used within a 
string, so the outputs of Listing 1 and Listing 2 are slightly different. 


Program Listing #1 

/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

/* C-MANSHIP * 

/* Chapter 7 * 

/* Listing 1 - Developed with Megamax C * 

jkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkJ 

#include <stdio.h> 

#include <osbind.h> 

char *pl, arrayl[] = "ABC"; 

int *p2, array2[] = (10, 11, 12}; 

main () 

{ 

int x, ch; 
pi = arrayl; 

printf("+0 pl=%ld &pl=%ld *pl=%d\n\n", pi, &pl, *pl ); 
for ( x=0; x<3; ++x ) { 

pi = Sarrayl[x]; 

printf("+%d pl=%ld &pl=%ld *pl=%d\n" ,x,pi,&pl,*pl); 

} 

printf( "\n" ); 

for ( x=0, p2=array2; x<3; ++x ) { 

printf ("+%d p2=%ld &p2=%ld *p2=%d\n" ,x,p2,&p2,*p2); 

++p2 ; 

} 

printf ( "\nPress any key\n" ); 

Cconin (); 

} 
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Program Listing #2 

j •k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k 

/* C-MANSHIP * 

/* Chapter 7 * 

/* Listing 2 - Developed with Megamax C * 

J •k'k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k'k-k'k-k-k-k'k-k'k-k'k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k-k-k-k-k-k'k-k'k j 

#include <stdio.h> 

#include <osbind.h> 

#define PRINT(Z) printf("+%d p=%ld &p=%ld *p=%d\n" ,x,Z,&Z,*Z) 

char *pl, arrayl[] = "ABC"; 

int *p2, array2[] = {10, 11, 12}; 

main () 

{ 

int x = 0, ch; 

pi = arrayl; 

PRINT (pi ); 
printf ( "\n" ); 
for ( x=0; x<3; ++x ) { 

pi = Sarrayl[x]; 

PRINT (pi ); 

} 

printf ( "\n" ); 

for ( x=0, p2=array2; x<3; ++x ) { 

PRINT ( p2 ); 

++p2 ; 

} 

printf ( "\nPress any key\n" ); 

Cconin (); 

} 
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CHAPTER 8 - STRUCTURES AND MORE ON POINTERS 

Structures offer a way to keep related data items together, allowing easy access to each element. 
Database applications are a perfect example. Suppose you're the owner of a store and want to keep 
track of your receivables. You'll need to know, at a minimum, the customer's name, address and 
amount owed. It would be nice if there were an array type that could store both character strings 
and floating point numbers. Guess what? Structures to the rescue. 

When we set up a structure, we're really defining a new data type, one that's custom designed for 
our own use. Each "member" of the structure can be any data type we want, even another structure. 
Let's set up a structure for our store's receivables: 

struct account { 

char name[20]; 
char address[36]; 
char city[30]; 
float balance; 

} ; 

The keyword struct, followed by the name account, tells the compiler we're setting up our own data 
type, and that we're going to call this data type account. The structure's members are declared in the 
same way we'd declare conventional variables, though enclosed with C's ubiquitous braces. The 
structure declared above contains four members: a 20-element character array called name, a 36- 
element character array called address, a 30-element character array called city, and a floating-point 
variable called balance. 

Now that we've declared our structure, we have a new data type at our disposal, but we still don't 
have a variable of that type we can use. Think about it for a minute. If we want an integer variable, 
we must declare it as type int. If we want a character variable, we must declare it as type char. So it 
follows that, if we want an account variable (the name we gave our new data type), we must declare 
it as type account: 


struct account record; 


We've just told the compiler we want a variable called record which is a 
structure of type account. That's all there is to it — almost. 

Filling It In 

We've got our variable record set up, but there's still one minor problem: it contains no data. As I'm 
sure you suspect, initializing a structure is going to be different from initializing the simpler data 
types. Well, yes...and no. 

struct account record = { 

"Clay Walnum", 

"15 Notreallygonnagivemyaddress Ave." , 

"Atariland, MA 06116", 

155.97 

} ; 

The main difference between this initialization and that of other data types is that we don't have to 
include the element's name along with the data. We have to fill in only the information. The compiler 
knows the first element goes into the field called name, the second into the field called address, etc. 
We gave it that information when we defined the structure type account. 

When initializing a structure, be sure to enclose the data in braces and separate each element with a 
comma. 
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Getting It Out 

We now have our structure declared and initialized with data. Just as we need access to each 
element of an array, we need access to each member of a structure. How can we get at the data? We 
simply refer to the name of the structure and the name of the element within the structure, 
separating each with a period: 

record.name 
record.address 
record.city 
record.balance 

The first example will give us the string "Clay Walnum." We can manipulate this data the same way 
we would any string of characters. For example: 

s = record.name; 

will point the character pointer s to the string stored in the first member of the structure record. 

The second and third examples are similar to the first. The fourth example will give us the floating¬ 
point value of 155.97. We might want to use it in this way: 

printf("Balance = %f\n", record.balance); 

Layers Upon Layers 

I stated that the elements of a structure could be of any data type, including another structure. Let's 
take the structure we've created one step further. It might be nice to have the city, state, and zip 
code in their own elements. We could, of course, just add a couple of members to our original 
structure. But what if we wanted, for the sake of clarity, to keep all the information within the 
member city? We'd do it like this: 
struct where { 

char c[20]; 
char s[2] ; 
char z[5]; 

} ; 


struct account { 

char name[20]; 
char address[36]; 
struct where city; 
float balance; 

} ; 


struct account record; 

Now take a deep breath, and we'll attempt to wade through the above example. Our structure 
account still contains the same information. The difference is that the member city is now a structure 
of type where, and where contains the members c, s, and z. 

Got it? Imagine the structure account as a big box. Inside this box are three other boxes called name, 
address, city, and balance. Inside the city box are three even smaller boxes called c, s, and z. 

Now when we refer to the city member, we need to access the nested members c, s, and z: 

record.city.c 
record.city.s 
record.city.z 

In the first case, we're accessing c, which is a member of city, which is a member of record. In the 
second, we end up with s, which is a member of city, which is a member of record. I bet you can 
figure the third one out for yourself. 
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More Layers! 

I'm not through confusing you, yet. Just as you can have arrays of integers or arrays of characters, 
you can have arrays of structures. In fact, in the case of the database for our imaginary store, arrays 
of structures are a necessity. What good is a database with only one entry? We could leave things 
the way they are and load the records from disk one at a time, but that would be inefficient. Imagine 
trying to sort a database that way. Not me, buddy. I want them all in memory where I can play with 
them fast. 

Arrays of structures aren't as scary as they sound. One small change to our structure variable 
declaration, and we've got it: 

struct account record[100]; 

We now have room for one hundred records of type account. 

Accessing each element of our structure array is just as simple: 

record[index].name 
record[index].address 
record[index].city.c 
record[index].city.s 
record[index].city.z 
record[index].balance 

As we vary index from zero to the maximum number of elements in our array, we can access each 
member as shown above. We also retain control over arrays that make up some of the members of 
our structure. For instance, if we wanted the third letter in the character array name: 

record[index].name[2] 

An Important Point 

In the last chapter, we talked about pointers. Can we use pointers with structures? Sure can. The first 
step is to declare our pointer, a simple process: 

struct account *sptr; 

Now that we have our pointer, we must initialize it: 

sptr = &record[0]; 


or 

sptr = record; 

The above assigns the address of the first byte of our array of structures to the pointer sptr. Suppose 
this address turned out to be 72000. Using what you've learned about pointers and structures, see if 
you can calculate the address we'd be pointing to if we added 1 to sptr. 

The answer is 72096. How did you do? Remember that a pointer is kept well informed about the data 
type it's associated with, even if that data type is one we made up, as is a structure, sptr knows that 
there are 96 bytes in each of our array elements. We get this figure by adding together the length of 
each structure member: 


name 30 

address 35 

c 20 

s 2 

z 5 

balance 4 


96 bytes 

Let's say that x is the length, in bytes, of the data type to which we're pointing. Then, when we 
increment a pointer, we're asking it to point to a location in memory which is x bytes ahead of our 
current location. In the case of our array, we're pointing to the next element, recordjl], which begins 
at an address 96 bytes higher than our current address, or a final address of 72096. 
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Pointing to a Member 

A pointer to the first member of a structure is only slightly useful. We need to access all of the 
members. As always, C is there with the answer. Assuming sptr equals &record[0], then: 

(*sptr).name equals record[0].name 
(*sptr).city.c equals record[0].city.c 

A more popular (and less cryptic) way of writing the above would be: 

sptr->name equals record[0].name 
sptr->city.c equals record[0].city.c 

Either method is fine and gives the same results. 

Functions and Structures 

The last thing we need to know in order to take full advantage of structures is how to pass them to 
functions. As has been evident throughout this chapter, structures are handled the same, for the 
most part, as any other data type. 

The most obvious method of passing information from a structure to a 
function is by value: 

total = add_em( record[index].balance, record[index+1].balance ); 
float add_em(x, y) 
float x, y; 

{ 

return (x + y); 

} 


Here, two values from our array of structures are passed into the parameters x and y. The values are 
added and the result returned to the calling function. 
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But what if we want to modify the contents of the structure directly? As in the past, we resort to 
pointers: 

change_em(Srecord[1]); 

change_em(sptr) 
struct account *sptr; 

{ 

sptr->name = "Felix"; 

} 

In the above example, we've passed the address of the second member of our array of structures to 
the function change_em(). This address is stored in the pointer sptr, where it's used to access the 
member name. 

The Listing 

This chapter's sample program is larger than anything we've done so far. I wanted to offer something 
moderately usable. There are many techniques in the program we haven't covered. In the next 
chapter, we'll clear up some of the leftover mysteries. At any rate, the program contains working 
examples of everything we've discussed here, as well as many other little tidbits you can sort 
through. 

What does it do? I thought you'd never ask. The program is a simple address database. You can enter 
addresses from the keyboard or disk, then print them to the screen or to the printer in label format. 
As I said, it's simple. There's plenty of room for enhancements. A sorting feature could be added, or 
maybe a fancier input routine. To keep data from scrolling off the screen, labels are limited to a 
maximum of eight. You could add code that would wait for a keypress each time the screen fills, then 
increase the number of addresses in the database. 

Program Listing #1 

j •*****************************************************j 


/* 

C-MANSHIP 

*/ 

/* 

Chapter 8 

*/ 

/* 

Listing 1 

*/ 

/* 

Developed with Megamax C 

*/ 


j*****************************************************j 

#include <stdio.h> 

#include <osbind.h> 

#define RETURN 13 
#define BACKSPACE 8 
#define MAX 8 
#define PRINTER_OFF 0 
#define NOFILE ((FILE *)0) 

FILE *fopen(); 

int work in [11]; 
int work_out[57]; 
int handle; 
int contrl[12]; 
int intin[128]; 
int ptsin[128]; 
int intout[128]; 
int ptsout[128]; 

struct name { 

char fname[30]; 
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char lname[30]; 

In¬ 
struct rec { 

struct name names; 
char street[30]; 
char city[30]; 


! ■k-k'k-k'k-k'k-k'k-k-k-k'k-k'k-k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k'k-k'k-k'k-k 

* MAIN PROGRAM 

•k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k'k-k'k-k'k-k'k-k'k-k'k-k'k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'kj 

main () 

{ 

int num^recs, /* Number of addresses in the file. */ 
load; /* File flag. */ 

char ch; 

struct rec address[MAX]; 

/* Open virtual workstation. */ 
open vwork (); 

/* Get the address data from disk or keyboard. */ 
num_recs = get_data ( address, Sload ); 

/* Convert integer flag to character-type data. */ 
ch=load; 

/* Output addresses to screen or printer. */ 
output ( address, num_recs ); 

/* Save address data to disk if it was entered */ 

/* from the keyboard rather than from disk. */ 

if ( ch=='N' | | ch== 'n' ) 

save_file( address, num_recs ); 

/* Wait for a key press. */ 
printf ( "Press key\n" ); 

Cconin (); 

/* Close the virtual workstation. */ 
v_clsvwk(handle); 

} 

j ■k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k 

* open^vwork () 

•k 

* Initializes a virtual workstation. 

•k-k'k-k'k-k'k-k'kk'k-k'k-k-k-k-k-k-k-k'k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k'k-k'k-k'k^ 

open^vwork () 

{ 

int i; 

for (i=0; i<10; work_in[i++] = 1); 
work in[10] = 2; 

v_opnvwk(work in, Shandle, work out); 

} 


^■k'k-k'k-k-k-kkk'k-k'k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-kk'k-k'k-k-k-k-k-k'k-k'k-k'k 

* get_data () 
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* Allows the user to choose to enter address records 

* either from disk or from the keyboard. The inputs 

* are a pointer to the array of structures that will 

* hold the data and a pointer to the flag that will 

* tell the program whether the data has been loaded 

* from disk or typed from the keyboard. The output 

* is the total number of records entered. 

J***************************************************** I 
get_data ( recp, load ) 
struct rec *recp; 
int *load; 

{ 

int num recs; 

/* Print the prompt. */ 

Cconws ( "Load file? " ); 

/* Loop until we get a proper keystroke. */ 
while ( (*load=Cconin())!=' Y' && *load!='y' 

&& *load!='N' && *load!='n' ); 

printf( "\n\n" ); 

/* If the user answered "N" to the prompt, get the addresses 
from the keyboard, or else get the addresses from the disk. */ 
if ( *load == 'N' || *load == 'n' ) 

num recs = get_records ( recp ); 

else 

num_recs = disk file ( recp ); 

/* Return the number of addresses that were entered. */ 
return ( num recs ); 

} 

/***•}************************************************** 

* get_records () 

* 

* Retrieves address data from the keyboard. The 

* input is a pointer to the structure that will hold 

* the address data. The output is the total number 

* of records entered. 

j*****************************************************j 

get_records ( recp ) 
struct rec *recp; 

{ 

int ans, /* Character storage. */ 

i; /* Record counter. */ 

/* Initialize our variables. */ 
ans = 'y' ; 
i = -1; 

/* Keep getting addresses until the user indicates */ 

/* that he is finished or until we run out of room. */ 
while ( (ans=='Y' || ans=='y') && i+l<MAX ) { 

++i; 

Cconws ( "FIRST NAME: " ); 
get_str ( recp->names.fname, 29 ); 

Cconws ( "\n LAST NAME: " ); 
get_str ( recp->names.lname, 29 ); 

Cconws ( "\n STREET: " ); 
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get_str ( recp->street, 29 ); 
Cconws ( "\n CITY: " ); 

get_str ( recp->city, 29 ); 

Cconws ( "\n\nAnother (y/n)? " ); 
ans = Cconin (); 
printf ( "\n\n" ); 

++recp; 

} 

/* Return the record count. */ 
return ( i+1 ); 


/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* disk file () 

k 

* Reads address records from a disk file. The input 

* is a pointer to the structure in which to store 

* the records. The output is the number of records 

* read. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

disk file(recp) 
struct rec *recp; 

{ 

FILE *p_file; 
char filename[15]; 
int num recs, x, 1; 


p_file = NOFILE; 

/* Get valid filename. */ 
while (p_file == NOFILE) { 

Cconws( "Filename: "); 
get_str(filename,14); 
printf ("\n\n") ; 

p file = fopen(filename, "r") ; 
if (p_file == NOFILE) 

printf ("No such file!\n\n" 


} 


/* Read in number of records in file. */ 
num^recs = getw(p_file); 

/* Read in all address records. */ 
for (x=0; x<num^recs; ++x) { 

fgets(recp->names.fname, 30, p file); 
1 = strlen ( recp->names.fname ); 
recp->names.fname[1-1] = 0; 
fgets(recp->names.lname, 30, p file); 
fgets(recp->street, 30, pfile); 
fgets(recp->city, 30, p_file); 

++recp; 

} 

/* Return number of records read. */ 
return (num recs); 


/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* output () 
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* Asks the user if the address records should be 

* sent to the printer or to the screen. The inputs 

* are pointer to the structure holding the records 

* and the number of records in the structure. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

output(recp, num^recs) 
struct rec *recp; 
int num_recs; 

{ 

int status, device; 

/* Initialize loop variable. */ 
status = PRINTER_OFF; 

/* Loop until records have been output. */ 
while (status==PRINTER_OFF) { 

/* Get device from user. */ 

Cconws( "Print to screen or printer (s/p)? "); 
device = Cconin(); 
printf( "\n\n" ); 

/* Send address records to requested device. */ 
if (device == 'p' || device == 'P' ) 

status = printer(recp, num_recs); 

else { 

screen(recp, num^recs); 
status = -1; 


/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* save_file () 

k 

* Writes the address records out to a disk file. The 

* inputs are a pointer to the structure holding the 

* records and the number of records in the structure. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

save file(recp, num recs) 
struct rec *recp; 
int num^recs; 

{ 

FILE *p_file; 
char r,x; 

char filename[15]; 

/* Ask if user wants to save file. */ 

Cconws ("Save file? "); 

while ((r=Cconin)! ='Y 1 && r! ='y' && r! ='N' && r!='n'); 

printf ("\n\n") ; 

if (r == 'Y' || r == 'y' ) { 

pfile = NOFILE; 

/* Loop until we get a valid filename. */ 
while (p_file == NOFILE) { 

Cconws( "Filename: "); 
get_str(filename, 14); 
printf ("\n\n") ; 
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/* If file doesn't exist, open it. */ 
if ((p_file=fopen(filename, "r")) == NOFILE) 
p file = fopen(filename, "w") ; 

/* If file does exist, check if okay to delete. */ 
else { 

p_file = NOFILE; 

Cconws("File already exists. Delete it? "); 
if ((r=Cconin ()) == 'Y' | | r == 'y' ) 

p file = fopen(filename, "w"); 
printf ("\n\n") ; 

} 

} 

/* Write out the number of address records. */ 
putw(num^recs, p_file); 

/* Write out all the address records. */ 
for (x=0; x<num recs; ++x) { 


fprintf(p file. 

"%s\n" , 

recp->names. 

fname); 

fprintf(p file. 

"%s\n" , 

recp->names. 

lname); 

fprintf(p file. 

"%s\n" , 

recp->street 

); 

fprintf(p file, 
++recp; 

"%s\n" , 

recp->city); 



} 

fclose(p_file); 

} 

} 

/•k-k'k-k'kic'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k-k 

* screen () 

-k 

* Writes the address records out to the screen. The 

* input is a pointer to the structure holding the 

* records and the number of records in the structure. 

•k-k'k-k'k-kk-k'k-kk-k'k-kk-kk-kk-k'k-kk-kk-k'k-k-k-k'k-k-k-k'k-k'kk'k-k'k-kk-k'k-kk-kk-kk-k-k'k^ 

screen(recp, num^recs) 
struct rec *recp; 
int num_recs; 

{ 

int x; 

/* Enter alphanumeric screen mode. */ 
v_enter cur(handle); 

/* Write out each line of each record. */ 
for (x=0; x<=num recs-1; ++x) { 

pos_cur(x,0); 

printf( "Record #%d\n", x+1); 
pos_cur(x,1); 

printf ("%s %s\n", recp->names.fname, recp->names.lname); 
pos_cur(x,2); 

printf( "%s\n" , recp->street); 
pos_cur(x,3); 

printf( "%s\n\n" , recp->city); 

++recp; 

} 

} 


/■k'k-k'k-k'k-k'k-k'k-k'kk'k-k'k-k'k-k'k-k'k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k 
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* printer () 

k 

* Writes the address records out to a printer. recp 

* is a pointer to the structure holding the 

* records and num^recs is the number of records stored 

* in the structure. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

printer(recp, num^recs) 
struct rec *recp; 
int num recs; 

{ 

int x, status, i; 

FILE *p_file; 

/* Wait for printer to be turned on. */ 
status = Cprnout(0); 
if (status == PRINTER_OFF) { 

printf("Turn on printer!\n" ); 
return (status); 

} 

/* Send each line of each record to the printer. */ 
for ( x=0; x<num recs; ++x ) { 

for ( i=0; i<strlen(recp->names.fname); ++i ) 
Cprnout(recp->names.fname[i]); 

Cprnout ( ' ' ); 

for ( i=0; i<strlen(recp->names.lname); ++i ) 
Cprnout(recp->names.lname[i]); 


Cprnout ( 

' \n ' 

) ; 

Cprnout ( 

' \r' 

); 

for ( i=0; 

i<strlen(recp->street); ++i 

Cprnout(recp->street [i]); 

Cprnout ( 

' \n ' 

) ; 

Cprnout ( 

' \r' 

); 

for ( i=0; 

i<strlen(recp->city); ++i ) 

Cprnout(recp->city [i]); 

Cprnout ( 

' \n ' 

) ; 

Cprnout ( 

' \r' 

) ; 

Cprnout ( 

' \n ' 

) ; 

Cprnout ( 

' \r' 

) ; 

Cprnout ( 

' \n ' 

) ; 

Cprnout ( 

' \r' 

) ; 

Cprnout ( 

' \n ' 

) ; 

Cprnout ( 

' \r' 

); 

++recp; 




} 

return (status); 

} 

/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* pos_cur () 

k 

* Positions the cursor on the screen. i is 

* the record number and 1 is the number of the line 

* within the record being printed. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkJ 

pos_cur(i,1) 
int i,1; 

{ 

int x, y; 
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/* If even-numbered record, position on */ 

/* right side of screen. */ 

if ( (i + 1)%2 == 0) 
x = 50; 

/* If odd-numbered record, position on */ 

/* left side of screen. */ 

else 

x = 10; 

/* Calculate vertical position of line. */ 
y = ((i/2)*5)+ 4 + 1; 

/* Position cursor. */ 
vs_curaddress(handle,y,x); 

} 

j •k-k-k'k-k-k-k'k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k-k'k-k-k-k'k-k-k-k'k-k-k'k'k-k-k-k'k-k-k-k'k 

* get_str () 

:k 

* Gets a string from the keyboard. s is a pointer 

* to a character array and mx is the maximum allowable 

* length of the string. 

'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k'k-k'k-k'k-k'k-k-k-k'k-k'k-k'k'k'k-k'k-k'k^ 

int get_str(s, mx) 
char s[]; 
int mx; 

{ 

int p, code; 

p = 0; 

/* Get character from console. */ 
code = Cconin(); 

/* Add character to string. */ 
while (code != RETURN && p <= mx-1) { 

if (code != BACKSPACE) { 
s[p++] = code; 

} 

/* Handle backspace. */ 
else if (p > 0) { 

s[—p] = ' \0 ' ; 
putchar(BACKSPACE); 
putchar ( ' ' ); 

putchar(BACKSPACE); 

} 

/* Get next character. */ 
code = Cconin(); 

/* Add null to end of string. */ 
s[p] = '\0' ; 

} 

if (p == mx) 

printf( "\r\n" ) ; 

} 
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CHAPTER 9 - MORE LOOPING STRUCTURES AND FILE I/O 

Everyone give a hearty cheer. This chapter we'll be finishing up the most grueling details of 
programming in C, so that next chapter we can start learning about GEM. It's been a long time 
coming, but you can't bake a cake until you've heated the oven, right? 

Chapter 8's program listing overflowed with new material. Let's tackle that first. 

Unfinished Business 

At the top of the listing, beneath the block of defines, you'll see a function, fopen(), being declared as 
returning a pointer to type FILE. If you think back, you'll remember that any time a function is going 
to return something other than an integer, it must be declared. But what the heck is FILE, anyway? 
We've never discussed this data type, have we? 

Actually, in a way, we have. In Chapter 8, we talked about structures, data types that are specifically 
tailored by the programmer. FILE is a structure defined in the stdio.h file, containing the data 
elements required to handle file I/O. 

Wait a minute. That fopen() isn't our function. Except for the function calls, this guy is nowhere to be 
found in our program listing. 

True. fopen() is a library function. Now, one would think that, if whoever composed the stdio.h file 
went to all the trouble to set up the FILE structure, he would have at least gone to the extra effort to 
make fopen() "ready to go," by declaring it as returning a pointer to FILE. 

For some strange reason, the version of stdio.h that comes with the Atari developer's kit doesn't 
include the declaration, so we must do it ourselves. If you have the Megamax compiler, however, you 
can delete this declaration from the program; they did award us the courtesy of finishing the job. 

A Quick Look at GEM 

Just beyond the file declaration for fopen(), there are declarations for a number of global arrays: 
work_in[], work_out[], contrl[], intin[], ptsin[], intout[], and ptsout[]. If you've looked at some of the 
C source code for various GEM programs in the public domain, or those published in magazines, 
you've noticed that these arrays are almost always present. In fact, you've probably seen them used 
in ST BASIC programs, as well. 

All the above arrays have one thing in common: they provide GEM a place to store or retrieve 
information about the program. This information can then be easily manipulated by the 
programmer. 

I know, I know. I told you we weren't going to be getting into GEM until Chapter 10. But we are going 
to learn a little about initializing a GEM program, since the cursor control functions I used in Chapter 
8's listing are found in the VDI portion of GEM. 

What's VDI? GEM is made up of many libraries of functions, each of which is responsible for handling 
a certain portion of the system's activities. These libraries are grouped into two major units, called 
AES (Application Environment Services) and VDI (Virtual Device Interface). The libraries making up 
the AES handle such things as windows, dialog boxes, menu bars and event processing. (An event is 
some action from the user, such as typing a letter or moving the mouse.) The VDI contains the 
subroutines to control the ST's graphics, as well as some mouse and cursor control functions. 

Since GEM is capable of handling several programs at once (such as using a desk accessory with a 
word processor), there has to be a way of keeping one job separate from another. GEM tackles this 
by assigning each program and its associated device (in our case, the screen) a "workstation" which 
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can then be referred to by an identifier known as a "handle." The first thing any GEM application 
must do is open a workstation. 

Which brings us back to the arrays that started this discussion. When we open a workstation, we 
have to tell GEM how we want the system's attributes initialized. What color should the text be? And 
should it be shadowed? Or maybe bold? What style fill do we want? Solid? Checkered? All these 
attributes should be placed in the array work_in[] before we open the workstation, since that's 
where GEM is going to expect to find them. 

We're not going to worry, at the moment, about which elements of the array hold information for 
which attribute. We're just going to take it on faith that work_in[10] should be initialized to 2, and 
the rest will be perfectly happy initialized to 1. 

After we've set up the array, we tell GEM to open the workstation with the v_opnvwk[] call: 

v_opnvwk(work in,Shandle,work-out); 

The parameter workjn is the address of our array work_in[], which contains the attribute 
information we wish to pass to GEM. And &handle is the address where GEM should store the 
handle, the integer value that will allow us to refer to this program's workstation. In our sample 
program, it's the address of the variable handle, which is defined after the work_in[] and work_out[] 
arrays at the top of the listing. The parameter work_out is, of course, the address of our array 
work_out[]. 

When we open the workstation, GEM will load the work_out[] array with all the information a 
programmer needs about the workstation. For instance, work_out[12] will contain the number of 
hatch styles available, while work_out[13] will contain the number of colors that can be displayed at 
one time. We don't have to be concerned with this information now, but it is important that you 
understand why we need these two arrays. 

You can see the mechanics of opening a workstation in the open_vwork() function of Chapter 8's 
program listing. Also, at the end of main(), notice the function call: 

v_clsvwk(handle); 

This closes the workstation to further output. The argument handle is the device handle passed to 
you by the v_opnvwk() call. 

And a Peek at VDI 

The remaining five arrays -- contrl[], intin[], ptsin[], ptsout[] and intout[] -- are directly associated 
with the VDI. The first three are used to pass information to the VDI routines, while the last two 
provide a means for the VDI to return information to the program. These arrays are used by GEM for 
its own purposes; you need do nothing more than declare them at the beginning of your program. 

Moving Along 

If you spent the time to examine Chapter 8's program listing, you probably wondered what was 
going on with this call: 

Cconws("FIRST NAME: "); 

This function does nothing more than write a string to the screen. Why didn't I just use printf() and 
avoid all this confusion? It has to do with another discovery I made concerning Megamax C. With 
Megamax, printf() will print only when it encounters a \n. This makes handling prompts tricky, if you 
want the user's input on the same line as the prompt. Resorting to CconwsQ solved this problem. 
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Three other new function calls, getw(), fgets(), and strlenQ, were used in the sample program in the 
disk_file() function. 

value = getw(file); 
fgets(string, n, file); 

1 = strlen(s) ; 

The function getw() reads a word (integer) from a disk file and stores it in value. The argument file is 
a pointer to a FILE structure. In our program, this function call is retrieving the number of records in 
our address file. 

The function fgets() reads a string from a disk file. In the above example, string is a pointer to a 
character array, n is the maximum number of characters to read from the file, and file is a pointer to 
a FILE structure. When fgets() is called, it will continue to read until it has read n-1 characters, finds a 
newline character (which is added to the end of the string), or gets an EOF. A null character is tacked 
onto the string after the read is complete. In our program, we're using fgets() to read in the strings 
that make up each record in our address file. 

Finally, the function strlen() simply returns the length of string s. We're using strlenQ to find the 
location of the newline character that was read in by fgets(), which we have to replace with a null. 
Let's say we just read in the name FRED. In our character array s, we now have the letters F, R, E, D, 
followed by a \n and a null. The function call 

1 = strlen ( s ); 

will return the length of the string up to the null, which in this case is 5. But our \n isn't really in s[5], 
is it? Remember: arrays start counting at 0. So to replace the \n with a null we do this: 

s[l-l] = 0; 

Another new function, fprintfQ, can be found in our program within the function save_file(): 

fprintf(p file, "%d\n", num recs); 
fprintf(p_file, "%s\n", recp->city); 

This function is almost identical to printfQ, the only change being the extra argument, the pointer to 
the FILE structure. 

In the first example, we're printing to the file the integer value stored in num_recs, followed by a 
newline. In the second, we're printing to the file the character string stored in the structure member 
city, also followed by a newline. 

The VDI Cursor Stuff 

If you look at the functions screenQ and pos_cur() in the program listing, you'll see the cursor control 
function calls I mentioned earlier. In order to take advantage of these functions, we must first make 
this call: 

v^enter cur(handle); 

This function call gets us out of graphics mode and into text mode. In this function, as with all the 
following, handle is the workstation identifier that was returned to us by the v_opnvwk() call. 
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We can position the cursor anywhere on the screen by passing the X,Y-coordinates to the function 
vs_curaddress(): 

vs^curaddress(handle,y,x); 

Notice that the coordinates are passed in the opposite order of what you'd expect; that is, Y followed 
by X. Also, keep in mind that we're now in text mode. The cursor location is based on character 
positions, not raster coordinates. In medium-resolution text mode, the screen's size is interpreted as 
80x24, whereas in graphics mode it's 640x200. Quite a difference! 

Printer Output 

Take a look at the function printerQ in the sample listing. The first thing we have to do is check to see 
if the printer is on. 

status = Cprnout(0); 

The line above accomplishes its task by sending a null character to the printer. If the printer times 
out, a 0 will be returned by the function. Another way to check the printer is with the function 
Cprnos() which returns a nonzero value if the printer is ready to receive: 

status = Cprnos(); 

Once we know that the printer is ready to respond, we can start sending text. There are several ways 
of doing this. The method I chose uses a function called Cprnout(), which sends characters to the 
printer one at a time. The format for this function call is: 

status = Cprnout (ch); 

Here, the value returned into status will be -1 if the character was sent okay, or 0 if, for some reason, 
the printer didn't respond. The variable ch is the character we want printed. 

In our program, we've omitted status. Since we've already checked the printer status, it's probably 
not necessary to check it again. However, in a real application program, we must be sure to check the 
value of status. How would we know if the printer ran out of paper or went off-line unexpectedly? 

Note also that we can send a character literal to the printer, as well as the character stored in a 
variable. In our program, for example, we're printing a space like this: 

Cprnout ( ' ' ) ; 

Because we need to print full strings rather than only a single character, we've set up a for loop for 
each of the strings, using the loop variable as an index into the character array. In this way, we loop 
through the string, sending it to the printer one character at a time. 

Finally, notice that we're ending each string by printing a \n and a \r. Without a line feed and carriage 
return, the strings will be printed side by side rather than one above the other. 

Odds and Ends 

That covers all the material from Chapter 8's sample program. Now we have a final task to complete 
before we can move on to GEM: touching on a few details of the C language we haven't yet covered. 

What do you make of the following line? 

z = (x<4) ? x : y; 

Believe it or not, this is nothing more than a shortcut version of: 

if (x < 4) 

z = x; 

else 

z = y; 

The ?: is a conditional operator that requires three operands. The first operand (within the 
parentheses) is the expression to be tested. If the expression is true, the statement yields the 
evaluation of the second operand (between the ? and :). If the first expression is false, the statement 
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yields the evaluation of the third operand (between the : and ;). Here's another example that'll get 
the highest value of two variables: 

highest = (x > y) ? x : y; 

C also has a construction similar to BASIC's ON...GOTO: 


switch (exp) { 
case 1 : 

printf("exp = 1"); 
break; 
case 2 : 

printf("exp = 2"); 
break; 
case 3 : 


printf("exp = 3"); 
break; 
default : 

printf("exp < 1 or > 3" 

} 


The switch statement works by first evaluating the expression in the parentheses, then checking the 
following labels to see if there's one that matches the expression's value. 

If there is, program execution jumps to the matching line and continues until it encounters the 
statement break. 

But what if there's no match? What if, in the above example, exp is not 1, 2, or 3? That's where the 
label default comes in. Program execution will jump to this line if none of the other labels match. 
Otherwise, if there's no default, program execution will jump to the next line following the end of the 
switch statement (after the closing brace). 

What happens if we leave out the break statements? Remember I said that, once the expression 
following switch is evaluated, the program jumps to the matching label and continues until it 
encounters a break. The program doesn't care if there's no break before the next label. It'll go on, 
past the succeeding labels (ignoring them), and execute every statement it finds -- until it either finds 
a break or reaches the closing brace. In the example above, if we left out all the break state- ments 
and exp evaluated to 2, the output would look like this: 

exp = 2exp = 3exp < 1 or > 3 

Similarly, if exp evaluated to 3, we would see: 

exp = 3exp < 1 or > 3 


A New Loop 

We've become used to the while and for loop constructions. Both are entry condition loops; that is, 
the loop conditional is checked before each iteration of the loop. There's another loop construct 
we've ignored so far, the do while loop. 

The do while construct is an exit condition loop. The loop conditional is evaluated after each 
iteration: 

x = 0 ; 
do { 

++x; 

printf("x = %d\n", x); 
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} while (x < 4); 

The above prints values of x from 1 to 4. Contrast that with: 

x = 0 ; 

while (++x < 4) { 

printf("x = %d\n", x); 

} 

which will print values of x from 1 to 3. 

Break, Continue, and Goto 

We talked about the break statement earlier, in conjunction with switch, but it can also be used to 
get out of for, while, and do while loops. When used in a nested loop construction, it only terminates 
the loop in which it's used. The outermost loops will continue normally. 

while (x < 10) { 

if (x == 5) break; 

else printf("x is not 5\n"); 

} 


Another method of affecting loop execution is with continue. When continue is encountered within a 
loop, the loop doesn't terminate, but, instead, starts the next iteration. 

x = 0 ; 

while ( (ch = getcharO) != '*') { 

if (ch = ' ' ) continue; 

s[x++] = ch; 

} 

Finally -- although I hate to mention it, due to its inevitable abuse -- C has a goto statement. The 
keyword goto is followed by the label identifying where program execution should continue: 

goto print_name; 

print^name: printf("Name: %s", name); 

Frankly, there's little or no use for the goto statement in a structured language like C. The same goes, 
though not as strongly, for break and continue, except when the former is used within a switch 
statement. There's almost always a more structured and elegant way to get around the use of these 
statements. If you're a BASIC programmer, it will take you a while to get accustomed to structuring 
your programs in such a way as to avoid the use of a goto. But, trust me, it can be done, and the 
results are much more readable than BASIC's typical tangle. 
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CHAPTER 10 - THE FIRST LOOK AT GEM AND THE VDI 

Hurray! The long wait is over. This chapter, as promised, we're going to start digging into GEM and 
learn how to get the most out of our STs. You've worked hard getting familiar with C, so give yourself 
a quick pat on the back for a job well done. Now put those thinking caps back in place. All set? 

A Review of GEM 

In Chapter 9, we took a brief look at what GEM really is. We stated that GEM (Graphics Environment 
Manager) is made up of many libraries of functions, each of which handles certain portions of the 
system's activities. These libraries are grouped into two major units, called the AES (Applications 
Environment Services) and the VDI (Virtual Device Interface). The AES contains the functions we need 
to handle windows, dialog boxes, menu bars and event processing. The VDI controls most of the ST's 
graphic capabilities, as well as providing some mouse and cursor control functions. 

What's so hot about GEM, anyway? Why all the hoo-hah? You've been using your computer for quite 
a while now, and you know one great advantage of GEM already: its ease of use. The system is 
designed in a logical, almost real-world sort of way, supplying icons that represent activities we're 
used to in everyday life, like file drawers and trash cans. That's why GEM's main screen is called a 
desktop. We can access calculators, documents, writing utensils, clocks, calendars, appointment 
books, and any of a hundred other items you might find on your desk. 

But another advantage of programming in GEM is its portability. It's been said that GEM is the most 
portable operating system in existence. This means your programs can easily be ported to other 
machines using the GEM environment, so your programming efforts are even more valuable. 

Presenting the VDI 

The VDI plays an important role in making your graphics programs operate on many different 
devices. Unfortunately, one of the crucial elements in the graphics interface, GDOS (Graphics Device 
Operating System) is not built into the current operating system. GDOS is the portion of the VDI 
which links the graphics functions to the drivers needed to assure that the graphics operate properly 
on all graphics devices. GDOS also makes it possible to load different fonts into your ST, using the 
standard VDI functions. 

At this time, however, we're concerned only with one device: the screen. 

The VDI functions 

The VDI provides the programmer with a series of functions that let him quickly draw many graphic 
shapes. This makes development of programs that rely heavily on graphics a breeze. If you 
programmed an 8-bit Atari (or still do), think of all the work involved in drawing a circle. The VDI 
provides a function that will draw any size circle we want — with a single call. There are also functions 
for drawing ellipses, lines, rectangles, rounded rectangles, arcs, pie slices and a number of other 
useful graphics. 

And it doesn't stop there. Each graphic function has a group of related attributes that may be set 
before the graphic is drawn, allowing various types of lines, fill patterns and colors. 

This chapter's sample program shows how to call most of the VDI's graphics functions. It was 
developed using the Megamax C compiler, but is also compatible with Alcyon C, the compiler that 
comes with the Atari Developers Kit. 

When the program is run, the first screen will show the different types of line styles available to you 
through the VDI. Each time you press a key, the program will display another set of graphics 
generated by a VDI function. 
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The Sample Program 

Let's take a look at the listing and see what's going on. The first thing we must do when writing a 
GEM program is initialize the application. We do this with the call: 

appl^int(); 

This tells the AES about our application and sets aside the resources the AES needs to function. Next, 
we must make the call: 

handle=graf handle(&gr hwchar, &gr hhchar, &gr_hwbox, &gr hhbox); 

This returns the handle for the currently open device or workstation, as well as the size of the system 
font. Because GEM is capable of having many programs in memory at once, each requires some 
identification, to keep commands for one program from messing up another. This is accomplished by 
assigning each program a handle. The variable handle in the above call is an integer value that 
identifies the current workstation. 

The graf_handle() call also returns some information about the system font. We must declare four 
variables of type integer to hold this information, then pass their addresses to the function. In the 
above call, gr_hwchar will get the width of a character cell in pixels; gr_hhchar will get the height of a 
character cell in pixels; gr_hwbox will get the width, in pixels, of a box large enough to hold a single 
character; and gr_hhbox will get the height, in pixels, of a box large enough to hold a single 
character. We won't be using any of this information now, but you should be aware of why we supply 
these variables. 

Let's Get Virtual 

The graf_handle() call returns the handle to the physical workstation. What we really need for our 
program is a handle to a virtual workstation. It's kind of tough to explain the difference, but I'll give it 
a shot. 

A particular device may have many virtual workstations, but only one physical workstation. The 
physical workstation is directly associated with the device itself, usually the screen. You can think of a 
virtual workstation as a "pretend" device. It has its own section of memory, and keeps its data and 
status completely separate from all other virtual workstations. When you activate an application 
(such as clicking on a desk accessory), it is bound to the physical workstation. In a sense, it becomes 
the physical workstation. 

We get the handle for our virtual workstation with the call: 

v_opnvwk(work in,Shandle,work-out); 

This function expects the system attributes to be in the work_in[] array. If you're not sure why we 
need the arrays work_in[] and work_out[], review Chapter 9. 

Polylines 

Now that we've got our workstation set up, we can get down to business. The first graphic we'll 
experiment with is called polylines. Those of you who are up on your linguistics know that the prefix 
poly means "many." Polylines are one or more lines connected from point to point, which allow the 
programmer to draw complex shapes with a single function call. The function call looks like this: 

v_pline(handle,num_pairs,pxy); 

The variable handle is, of course, the handle returned from the v_opnvwk() call. Every function we 
use requires this handle. That way, we're sure we won't mess with another application which may be 
in memory at the same time. If we're writing a desk accessory to be used with a word processor, for 
example, we want to be positive we don't change anything in the word processor application. 
Otherwise, we're liable to have an irritated user, to say the least. 
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The parameter pxy is a pointer to an array of integers which holds each of our polyline's end points in 
X,Y pairs. For instance, if we wanted to draw a box, pxy[] might look like this: 

int pxy[]={24,18,176,18,176,118,24,118,24,18 } 

The integer parameter num_pairs is the number of coordinate pairs in the pxy array. By the way, the 
pxy values are pixel values; in other words, in a low resolution screen we'd have possible values of 0- 
319 for the X-coordinates and 0-199 for the Y-coordinates. 

As I mentioned previously, there are a number of attributes we can set for each of the VDI graphics 
functions. For polylines, we can set the color, type and width, and the end style. We set the color 
with: 

vslcolor(handle,color); 

Here, color is an integer from 0 to the device maximum (low resolution=15, medium resolution=3, 
and high resolution^). If we use a number higher than the maximum, the function will default to 
color 1. On the ST, the default color palette, starting with 0 and ending with 15, is white, black, red, 
green, blue, cyan, yellow, magenta, white, black, light red, light green, light blue, light cyan, light 
yellow and light magenta. The function will return the color value chosen. 

If we're drawing a line at the smallest width, we can choose between six system line types with: 

vsl_type(handle,type); 

Here, type is an integer value from 1 to 7 as follows: 


1 

solid 


2 

long dash 


3 

dots 


4 

dash dot 


5 

dash 


6 

dash dot dot 


7 

user defined 



Type 7 lets you set up your own line types, but we're not going to get into that now. 

When you're drawing lines, you can also choose an end style with the call: 

vsl ends(handle,endl,end2); 

In this case, endl and end2 are integer values from 0 to 2. A value of 0 will yield a square end, 1 will 
get you an arrow, and 2 will result in a rounded end. The variable endl is the beginning style, and 
end2 is the ending style. 

Finally, we can set the thickness of our lines with the call: 

vsl width(handle,width); 

The variable width must be an odd positive integer. The line will be set to the closest width less than 
or equal to the value of width. The value chosen is returned from the function. 

Rounded Rectangles 

We can employ v_pline() to draw a standard square-cornered box, but the VDI also supplies a 
function which will let us draw rectangles with rounded corners. The function 
is called in this manner: 


f \ 
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v rbox(handle,pxy); 


Once again, we tell GEM where to draw our rectangle with the pxy array, except this time we must 
supply only the pixel coordinates of the lower-left and upper-right corners. The line attributes — 
color, style and width — are used with v_rbox(), allowing a wide variety of rectangles. 


Filled Rounded Rectangles 

If you want a solid, rounded rectangle, you can make this function call: 

v_rfbox(handle,pxy); 

The pxy array is used the same way as in v_rbox(), supplying the function 
with the lower-left and upper-right corners. The body of the rectangle is filled with the active fill 
pattern, which we'll see how to set later on. The default is a solid fill. 

Circles 

Want to draw a circle? No sweat! Just use this function call: 

v_circle(handle,x,y,radius); 

The integer parameters x and y are the pixel coordinates of the circle's center, 
radius is, obviously, the circle's radius (also an integer). The v_circle() function, 
the current fill attributes. 


o 

and 

like v_rfbox(), uses 



Polymarkers 

Polymarkers are a number of predefined shapes you can use in your graphics. You call the function 
this way: 


v_pmarker(handle,number,pxy); 


The integer parameter number is the number of markers you wish to draw. Coordinates for each 
marker are stored in the pxy array, one X,Y pair for each marker. 

But what do these markers look like? You have a choice of six predefined 
shapes which (from 1 to 6, respectively) are dot, plus sign, asterisk, square, 
diagonal cross) and diamond. 

To set the polymarker type, call: 

vsm_type(handle,type); 


• + * 

12 3 

■ x ♦ 


Here, type is an integer from 1 to 6. If you should choose a value out of this range, the function will 
select the asterisk as a default. The value chosen will be returned from the function. 

There are two other attributes which affect polymarkers: color and height. Color is set with the call: 

vsm color(handle,color); 


Here, color is an integer from 0 to the device maximum. All the rules of the vsl_color() call apply in 
this case. 
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You can change the size of all polymarkers, except the dot (which always appears in the smallest 
size), with the call: 

vsm height(handle,height); 

Here, the integer parameter height is the polymarker's size on the Y-axis. Actual height will be the 
greatest height available on the device, less than or equal to the height parameter. 

Filled Rectangles 

Solid rectangles can be drawn with the call: 

v_bar(handle,pxy); 

As usual, the lower-left and upper-right corners are stored in the pxy array. The 
active fill attributes are used to color the body of the rectangle. 



Ellipses 

An ellipse looks something like a squashed circle or a solid oval. You can draw 
it with the call: 

v_ellipse(handle,x,y,xrad,yrad); 

Here, the integers x and y denote the ellipse's center point, and the integers xrad and yrad are the X- 
and Y-radii in pixels. Once again, the active fill attributes are used. 

Arcs 

Arcs are simple to draw, with this call: 

v^arc(handle,x,y,radius,bang,eang); 

The integers x, y, and radius are the X,Y-coordinates of the center and the 

radius, respectively. The integers bang and eang are the beginning and ending angles of the arc, in 
tenths of a degree. The following diagram illustrates the possible angle values: 


91 

/ 

1800 / 

/ 

o 

/|'- 

CN 

/ 

/ 

DO 




Pie Slices 


Here's a handy function that'll help you draw those fancy pie charts. To draw 
a pie slice, use the call: 

v_pieslice(handle,x,y,radius,bang,eang); 
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The parameters are the same as those for the arc function. The body of the pie slice will be colored 
by whatever fill pattern is active. 
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Fill Patterns 

GEM supplies us with many patterns we can use to fill our figures. There's a series of functions to let 
us set these patterns up the way we want them. The first step is the function call: 

vsf interior(handle,style); 

Here, style is an integer 0 to 4. The values are interpreted as follows: 

0 Hollow (background color) 

1 Solid 

2 Pattern 

3 Hatch 

4 User-defined 

If you choose style 0 or 1, you need go no further, but style 2 allows you to choose between 24 
different patterns, and style 3 provides 12 hatch styles. You choose the pattern you wish to use, with 
the call: 


vsf_style(handle,style); 

Here, style is an integer value from 0 to 23. Consult your reference manual to see what these styles 
look like (or run the sample program). 

The color of your fill is selected with the call: 

vsfcolor(handle,color); 

All the rules for the vsl_color() function apply here, also. 

Finally, you can choose between a visible or invisible border for your fill, with the call: 

vsf_perimeter(handle,vis); 

Here, vis is any integer. A value of 0 will give you an invisible border; any other value will cause the 
border to be drawn in the current fill color. 

Use Those Tools! 

Now that you've been introduced to many of the graphics functions available to you through the VDI, 
study the sample program to see them in action, then take some time and experiment with the VDI 
on your own. See if you can write a program to draw a simple picture, maybe a graph or two. 
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Program Listing #1 

j •***************************************** / 

/* C-MANSHIP, LISTING 1 */ 

/* CHAPTER 10 */ 

/* DEVELOPED WITH MEGAMAX-C */ 

/ ***************************************** j 

#include <osbind.h> 

int work in [11], work-out[57]; 
int handle; 

int contrl[12], intin[128]; 

int ptsin[128], intout[128], ptsout[128]; 

int gr hwchar, gr hhchar, gr hwbox, gr hhbox; 

main () 

{ 

appl_init(); 
open vwork(); 
do_pline(); 
do_roundrec(); 
do_froundrec(); 
do_circle(); 
do_pmarker(); 
do_bar(); 
do ellipse (); 
do_arc(); 
do_pieslice(); 
do_fills(); 
v_clsvwk(handle); 
appl_exit(); 


open vwork() 

{ 

int i; 

for (i=0; i<10; work^in[i++] = 1); 
work_in[2] = 2; 

handle = graf handle(&gr hwchar,&gr hhchar,&gr hwbox,&gr hhbox); 
v_opnvwk(work in, Shandle, work out); 


do_pline() 

{ 

int pxy[4]; 


int 

color, end. 

type. 

width; 

pxy | 

[0] = 30; 

pxy[1] 

= 20; 

pxy | 

[ 2 ] = 280; 

pxy[3] 

= 20; 

end 

= 0; width 

= l; 



v clrwk(handle); 

for (color=l; color<5; ++color) { 
vsl_color(handle,color); 
vsl ends(handle,end,end); 
vsl width(handle,width); 
v_pline(handle,2,pxy); 
pxy[l] += 10; pxy[3] += 10; 
end t= 1; width += 2; 

} 
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vsl width(handle,1); 
vsl_ends(handle,0,0); 
vslcolor(handle,1); 
for (type=l; type<7; ++type) { 
vsl_type(handle,type); 
pxy[l] += 10; pxy[3] += 10; 
v_pline(handle,2,pxy); 

} 

Cconin(); 

} 

do_roundrec() 

{ 

int pxy[4]; 

int color, width; 

pxy[0] = 10; pxy[1] = 10; 

pxy[2] = 300; pxy[3] = 190; 
width = 1; 
v_clrwk(handle); 
vsl_type(handle,1); 
for (color=l; color<7; ++color) { 
vsl_width(handle,width); 
vsl_color(handle,color); 
v rbox(handle,pxy); 
width += 2; 

pxy[0] += 20; pxy[l] += 20; 
pxy[2] -= 10; pxy[3] -= 10; 

} 

Cconin(); 

} 

do_froundrec() 

{ 

int pxy[4]; 
int color; 

pxy[0] = 10; pxy[1] = 10; 

pxy[2] = 300; pxy[3] = 190; 
v_clrwk(handle); 

for (color=l; color<7; ++color) { 
vsf_color(handle,color); 
v rfbox(handle,pxy); 
pxy[0] += 20; pxy[l] += 20; 
pxy[2] -= 10; pxy[3] -= 10; 

} 

Cconin(); 

} 

do_circle () 

{ 

int color, radius; 

v^clrwk(handle); 
radius = 100; 

for (color=l; color<8; ++color) { 
vsf_color(handle,color); 
v_circle(handle,150,100,radius); 
radius -= 15; 

} 

Cconin(); 
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} 

do_pmarker() 

{ 

int color, height, type; 
int pxy[2]; 

v_clrwk(handle); 
pxy[1] = 10; 

for (type=l; type<7; ++type) { 
vsm_type(handle,type); 
height =2; pxy[0] = 10; 
for (color=l; color<6; ++color) { 
vsm^color(handle,color); 
vsm height(handle,height); 
v_pmarker(handle,1,pxy); 
height += 16; pxy[0] t= 60; 

} 

pxy[l] += 35; 

} 

Cconin(); 

} 

do_bar() 

{ 

int pxy[4], color; 

pxy[0] = 10; pxy[l] = 190; 
pxy[2] = 300; pxy[3] = 10; 
v_clrwk(handle); 

for (color=l; color<6; ++color) { 
vsf_color(handle,color); 
v_bar(handle,pxy); 
pxy[0] += 25; pxy[l] -= 20; 
pxy[2] -= 20; pxy[3] += 10; 

} 

Cconin(); 

} 

do_ellipse() 

{ 

int color, xradius, yradius; 

v^clrwk(handle); 
xradius = 150; yradius = 100; 
for (color=l; color<ll; ++color) { 
vsf_color(handle,color); 

v_ellipse(handle,150,100,xradius,yradius); 
xradius -= 15; 

} 

Cconin(); 

} 

do_arc() 

{ 

int color, radius, bang, eang; 

v_clrwk(handle); 

vsl width(handle,3); 

bang = 900; eang = 0; radius = 10; 

for (color=l; color<6; +tcolor) { 
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vsl_color(handle,color); 

varc(handle,150,100,radius,bang,eang); 

bang += 60; eang -= 60; radius += 20; 

} 

Cconin(); 

} 

do_pieslice () 

{ 

int color, radius, bang, eang; 
v_clrwk(handle); 

radius = 100; bang = 3200; eang = 600; 
for (color=l; color<6; ++color) { 
vsf_color(handle,color); 

v_pieslice(handle,150,100,radius,bang,eang); 
radius -= 15; bang -=200; eang -= 100; 

} 

Cconin(); 

} 

do_fills() 

{ 

int pxy[4], style, i, num, x; 

pxy[0] = 50; pxy[l] = 30; 

pxy[2] = 250; pxy[3] = 170; num = 25; 

for (i=2; i<4; +ti) { 

vsf_color(handle,i); 
vsf_interior(handle,i); 
for (style=l; style<num; ++style) { 
vsf^style(handle,style); 
v_clrwk(handle); 
v_bar(handle,pxy); 
for (x=0; x<32000; ++x); 

} 

num = 13; 

} 

Cconin(); 

} 


Port: HYPertext by Lonny Pursell & PDF by DrCoolZic (jig) - VI.0 Oct. 2010 


Page 97/321 


C-MANSHIP COMPLETE - by CLAYTON WALNUT 


CHAPTER 11 - VDI TEXT FUNCTIONS 

Those of you who programmed the 8-bit Ataris were limited in your text displays. Sure, you had 
graphics 1 and 2, which endowed your computer with oversized text in four colors, and you could, 
when in graphics 0, inject life with some inverse video. 

If those alternatives did nothing to satisfy your critical eye, you could always take refuge in a 
redesigned character set. And, if you were into self-brutalization — or were desperate to the point 
where opened wrists seemed preferable to another moment of programming — you could draw your 
characters pixel by pixel, line by line, until your masterwork emerged amidst the ruins of your mental 
health. 

But those are bygone times. Now you own an ST. Because the ST's screen is bit-mapped rather than 
character-mapped, you may fire your shrink and discard all schemes of self-destruction. Text, like any 
other graphic, is drawn on the screen. 

Stop right there! Wasn't it the drawing of text on the 8-bits — that ghastly alternative to the normal 
displays — that forced many talented bit-and-byte managers to take up residence in the local 
Institute for the Incredibly Nervous? Yes, indeed. But, on the ST, GEM's VDI takes on the task, 
supplying the programmer with simple functions to graphically manipulate text. There are about two 
dozen text sizes available, as well as numerous special effects, which can be combined in any way the 
programmer sees fit. 

To get a quick introduction to the VDI text functions, type in this chapter's program listing, compile 
and run it. Use the mouse to click on the menu options. Clicking the left button when viewing a demo 
screen returns you to the menu; clicking the right button when at the menu returns you to the GEM 
desktop. 

Who's a Dummy? 

Now that you've seen some of the things you can do with text on an ST (I suspect you've seen this 
stuff before), let's dig into the listing. The program first calls appl_init(), after which it opens a virtual 
workstation. We discussed these procedures in Chapter 10, but take a look at the parameters for the 
graf_handle() call. See something a little strange? Four of the parameters are the address of the 
variable dummy. 

In Chapter 10, I told you that graf_handle() returns information about the system font. This 
information is stored in four variables whose addresses you pass with the call. In this chapter's demo 
program, we've no need for this information, so why clutter up the program with extra variables? 

The graf_handle() call doesn't care where it stores the information, as long as you give it an address. 
In fact, it doesn't even care if you give it the same address for all four values. It'll happily store one 
value on top of the previous one (wiping the older value out, of course; you'll have no way to retrieve 
any but the last). 

The integer variable dummy is used throughout the program in just this way. Anytime we must 
supply storage for a dispensable value, we'll use the dummy variable. 

Converting Between Resolutions 

After we've got our workstation opened, function init() sets up the program for our current 
resolution, then changes the mouse pointer to the hand icon. In order to do this, we first need to get 
the resolution. We do this with the call: 
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res = Getrez(); 

This returns an integer from 0 to 2. A value of 0 means the screen is currently in low resolution; a 
value of 1 indicates medium resolution; and a value of 2 tells you you're in high resolution. This 
function is defined in the osbind.h file, and is a part of the XBIOS. 

In low resolution, the screen dimensions are 320x200. In medium, the horizontal resolution is 
doubled, giving us a screen 640x200. Finally, in high resolution, both the horizontal and vertical 
resolutions are doubled (as compared to low resolution), yielding a screen 640x400. These 
relationships are important if we're going to write software compatible with all three resolutions. 

Let's say we're in low resolution. We draw a rectangle with the coordinates 20 20, 60 20, 60 40, 20 40 
and 20 20 (these are the coordinate pairs you would load into the pxy array before calling v_pline()). 
Now we switch to medium resolution and draw the same rectangle. 

What happened? The rectangle is only half as long, right? This is because the horizontal resolution 
has been increased by a factor of 2; the screen pixels are half as wide, so they produce a rectangle 
half as long. If we want the rectangle the same size in medium resolution as in low (and in the same 
place on the screen), we have to double the value of the horizontal coordinates. A rectangle drawn in 
medium resolution between the coordinates 40 20,120 20, 120 40, 40 40 and 40 20 will look like one 
drawn with the previous coordinates in low resolution. 

Now let's use the medium resolution coordinates to draw the same rectangle in high resolution. 
Whoops! The figure is the same length, but now it's only half as high. No surprise, right? 

The vertical dimension of a high resolution screen is twice that of low or medium resolution screens. 
If we want to draw that same rectangle yet again, but in high resolution, we must multiply the 
vertical coordinates by a factor of 2, giving us 40 40, 120 40, 120 80, 40 80 and 40 40. 

Text output is affected by changes in resolution, too. In medium resolution, text is half as wide as in 
low. High resolution, which uses a different font, yields text the same width as that in medium 
resolution, but half as high. 

How's all this handled in init()? Well, let's see. Once we get the resolution with a call to GetrezQ, we 
use the returned value in a switch statement to set h_factor (horizontal factor), v_factor (vertical 
factor) and t_factor (text factor) to their appropriate values. We'll use these values in calculating 
screen coordinates for the resolution we're in. 

Some of the shapes to be drawn by our program have coordinates hard coded into arrays. This saves 
us from setting up a pxy array each time we draw one of these shapes; we can, instead, pass the 
address of the array that contains the coordinates. 

To avoid calculations later on in the program, we immediately modify these arrays for our current 
resolution. The for loop near the bottom of init() accomplishes this, by multiplying each element of 
the array by one of the factors initialized by the switch statement. The figures whose coordinates are 
stored in these arrays will then be displayed properly in any resolution. 

Of Mice and C 

The function initQ's last task is to change the mouse form from the arrow to the hand. The call that 
accomplishes this is: 

graf^raouse (form,mouse form); 

Here, form is an integer value from the table below and mouse_form is the address of a 35-element 
array containing the data for the mouse form. At this point, we're not going to discuss this array, 
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since it pertains to user-defined mouse forms rather than those supplied by the system. We'll discuss 
custom mouse forms in an upcoming chapter. 

The acceptable values for form are as follows: 


0 

* 

Arrow 

1 

I 

Line cursor 

2 

C$n 

Bee 

3 


Pointing hand 

4 


Flat hand 

5 

+ 

Thin crosshair 

6 

+ 

Thick crosshair 

7 


Outlined crosshair 

255 


User-defined mouse form 

256 


Hide mouse form 

257 


Show mouse form 


Any value from 0 to 7 will yield the mouse form shown. A value of 255 directs the function toward a 
user-defined mouse form stored in the mouse_form array. A value of 256 removes the mouse form 
from the screen, and a value of 257 restores it. As we'll see later, the ability to hide the mouse form 
is critical when drawing on the screen. 

The graf_mouse() function is a part of GEM's AES libraries. 

Menus and Varmints with Buttons 

The main program loop, found in do_menu(), utilizes the mouse for menu selection. The outer while 
loop repeats the menu process until the user wishes to exit the program, while the inner while loop 
samples the mouse until one of the buttons is pressed. 

Also within the inner loop is a call to mouse_print(). This function (found at the end of the listing) 
prints the coordinates of the mouse in the upper-left corner of the screen (actually, it'll print any two 
integers). I use this function to help me find the mouse X,Y-positions I need for my test statements. 
For instance, when writing this chapter's sample program, I used mouse_print() to determine what 
coordinates fell within each of the menu selections. Once the program was completed, I thought 
that, rather than delete mouse_print() from the listing, I'd leave it for you to fool with. What a guy, 
huh? 

Also, there are a couple of interesting function calls in mouse_print(). One of them, v_gtext(), we'll be 
using extensively, since it's the VDI function that displays text. The syntax for this call is: 

v_gtext (handle,x,y,string); 

The integers x and y are the location the text is to be printed, and string is a pointer to the text. (You 
may use a string literal within the call by enclosing it in quotes.) Remember that an array name (a 
string is an array of character) is a pointer. Since v_gtext() will handle only strings, how do we output 
other forms of data to the screen? What if we're writing a game and need to display a score? No 
problem. All we have to do is convert the data we want to print into a string. The following example 
will prepare an integer for printing with v_gtext(): 
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sprintf (s,"%d",i); 

The parameter s is the address of the string where the function is to store the converted data. (Don't 
forget to leave space for the null!) The rest of the parameters are the same as for printf(). If you're a 
little fuzzy on printf(), review Chapter 1. 

Getting back to do_menu(), once a button press is detected, a series of if/else statements check 
which button was pushed and the location of the mouse at the time. The VDI function that returns 
the mouse status is: 

vq_mouse (handle,Sbutton,&mx,&my); 

The parameter handle is, of course, the handle that was returned by the v_opnvwk() call. The 
parameters &button, &mx, and &my are the addresses of integer variables that will hold the button 
pushed, the mouse's X-position, and the mouse's Y-position, respectively. The value returned in 
button will be 0 if no button is pressed, 1 if the left button is pressed, 2 if the right button is pressed, 
and 3 if both buttons are pressed. 

After we exit the inner while loop, we check for a button value of 1 (left button pressed). If the left 
button was pressed, we then check the mouse coordinates at the time the button was pressed, to 
see if the pointer was within one of our menu selections. If it wasn't, repeat retains its true condition, 
and the outer while loop is repeated. 

If the mouse pointer was within the menu, we perform the appropriate function, redraw the menu, 
then return to the main while loop (repeat is still true). If button equals 2 (right button pressed), we 
set repeat to 0, which breaks us out of the main loop and returns us to main(), where we close the 
virtual workstation and return to the desktop. 

Notice that, when checking for mouse coordinates, we're utilizing h_factor and v_factor. Just as 
when drawing a shape, the horizontal and vertical mouse coordinates are dependent on the current 
resolution. We must multiply each coordinate in the if statements by the appropriate factor. 

Text Effects 

The ST has several built-in text effects you can use to enhance your programs. Text can be printed 
bold, light intensity, skewed, underlined, outlined, or any combination of the above. The function 
do_effects() in the sample program demonstrates these effects. 

First, a call to v_hide_c() hides the mouse form, then v_clrwk() clears the screen. The text color is set 
with the call: 

vst_color (handle,color); 

Here, color is an integer from 0 up to the maximum colors available for the current resolution. (You 
know what handle is, right?) Next, we set the text height (we'll cover this function a little later) and 
enter the loop that prints the text. The different effects are set with the call: 

vst_effects (handle,effect); 

Here, the bits of the integer effect are set as below: 
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Bit 

Value 

Effect 

0 

1 

Bold 

1 

2 

Light 

2 

4 

Skewed 

3 

8 

Underlined 

4 

16 

QvflMaol 


Note that the value in the bit column is the number of the bit to set, not the value to send to the 
function. You need to do some binary arithmetic to arrive at the decimal values shown in the second 
column. Any combination of effects can be used by adding the values together. For instance, if you 
want just bold text, the parameter effect in the above call should be set to 1; if you want underlined 
and bold text, effect should be set to 9 (1+8); for skewed, outlined, bold text, effect needs the value 
21, and so on. 

Text Height 

As I mentioned earlier, the ST is capable of displaying text in many different heights. Best of all, you 
may mix these heights on the screen in any way you wish. To set the height of text to be printed, use 
the call: 


vst height(handle,height,&char w,&char_h,&cell_w,&cell h); 

The integer height is the requested height, and the parameters &char_w, &char_h, &cell_w, and 
&cell_h are pointers to integer. Respectively, the values returned in these addresses are the 
character width, the character height (from the base line to the top of the cell), the cell width, and 
the cell height. In the sample listing, since we don't need this information, we just return all these 
values to our old standby, dummy. 

Another function we can use to set text height is: 

vst_point(handle,point,Schar w,Schar h,&cell w,&cell h); 

Here, point is the height of text in points (a point equals 1/72 inch). The other parameters are the 
same as for vst_height(). 

Text Rotation 

The GEM operating system allows text to be printed at any angle. Unfortunately, the ST 
implementation of GEM allows rotation in 90-degree increments only. To set the base line rotation of 
the text, use the call: 

vst rotation (handle,angle); 

The integer angle is the angle of rotation in tenths of degrees. Because of the limitation placed on 
this function for the ST, this value must be 0, 900,1800 or 2700. 

In the sample listing, the function do_rotate() demonstrates the use of text rotation. Handy for 
graphs! 

Mouse Prestidigitation 

In all cases, before we draw something on the screen, we must hide the mouse form. If we don't, we 
may find a block of the old screen pasted in over the new one as soon as the mouse is moved. This 
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may seem peculiar at first, but the logic behind it is simple. In order to allow mouse movement, the 
operating system must save for later redraw the section of the screen covered by the mouse cursor. 
When the mouse is again moved, the screen is restored by "pasting" back the saved block. The saved 
screen block remains unchanged if we draw to the screen, so when the mouse is moved, and GEM 
pastes in the old block, we may find a portion of the old screen coming back to haunt us. 

The VDI provides the following functions for turning the mouse form on and off: 

v_hide_c (handle); 
v_show_c (handle); 

There's something to keep in mind when using these functions. Every call to v_hide_c() must have a 
corresponding call to v_show_c() — unless, of course, you don't plan to see your mouse again. This 
doesn't mean you can't call v_hide_c() twice in a row; it just means that if you do call it twice in a 
row, you must also call v_show_c() twice to get your mouse back. 

Break Time 

Now that you've learned a good deal about the VDI and how to use a mouse, you have the tools to 
begin some serious GEM programming. The best way to become confident with these tools is to use 
them. So, practice what you've learned. 


Program Listing #1 

/ -kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk j 

/* C-MANSHIP, LISTING 1 */ 

/* CHAPTER 11 */ 

/* DEVELOPED WITH MEGAMAX-C */ 

f -k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k J 

#include <osbind.h> 

#define BLACK 1 
#define RED 2 
#define GREEN 3 
#define HOLLOW 0 
#define SOLID 1 
#define HAND 3 
#define NORMAL 0 

int work in [11], work-out[57]; 

int contrl[12], intin[128]; 

int ptsin[128], intout[128], ptsout[128]; 

int mouse form[35]; 

int recl[] = {106,150,206,50}; 

int rec2[] = {108,148,204,52}; 

int linel[] = {108,84,204,84}; 

int line2[] = {108,116,204,116}; 

int res, h_factor, v^factor, t_factor; 
int handle, dummy; 

main () 

{ 

appl_init(); 
open vwork(); 
init(); 
do_menu(); 
v clsvwk(handle); 
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appl_exit(); 

} 

do^menu() 

{ 

int repeat, button, mx, my; 

repeat = 1; 
draw^menu(); 
while (repeat) { 
button = 0; 
while (button == 0) { 

vq_mouse(handle,Sbutton,&mx,&my); 
mouse_print (mx,my); 

} 

if (button == 1) { 

if (mx>112*h_factor && mx<199*h factor) { 

if (my>54*v factor && my<81*v factor) { 
do_effects(); 
draw menu(); 

} 

else if (my>86*v factor && my<113*v_factor) { 
do_height(); 
draw menu(); 

} 

else if (my>118*v_factor && my<145*v_factor) { 
do_rotate(); 
draw menu(); 

} 

} 

} 

else if (button == 2) 
repeat = 0; 

} 

} 


do_effects() 

{ 

int x, y, effect, b_effect, n_effect, height; 


v hide_c (handle); 
v clrwk (handle); 
vst^color (handle,BLACK); 
if (res == 0) 

height = 4; 

else 

height = 8; 

vst height (handle,height,Sdummy,Sdummy,Sdummy,Sdummy); 
beffect = 1; 

for (x=5*h factor; x<260*h_factor; x+=62*h factor) { 
n^effect = 1; 

for (y=25*v^factor; y<126*v factor; y+=25*v^factor) { 
effect = b_effect | n_effect; 
vst_effects (handle,effect); 
v_gtext (handle,x,y, "EFFECTS" ); 
n effect <<= 1; 

} 

beffect <<= 1; 

} 
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v_show_c (handle); 
button_wait(); 

} 

do_height() 

{ 

int height, x, y; 

v_hide_c (handle); 
v_clrwk (handle); 
vst_effects (handle,0); 
for (height=l; height<27; ++height) { 
x += 8; y += 7; 

vst_height (handle,height,&dummy,Sdummy,Sdummy,Sdummy); 
v gtext (handle,x*h factor,y*v_factor, "Height" ); 

} 

v_show_c (handle); 
button_wait(); 

} 


do_rotate () 

{ 

int angle; 

v_hide_c (handle); 
v_clrwk (handle); 

vst height (handle,8,Sdummy,Sdummy,Sdummy,Sdummy); 
for (angle=0; angle<2701; anglet=900) { 
vst_rotation (handle,angle); 

v gtext (handle,160*h_factor,96*v factor, "ROTATION" ); 

} 

vst_rotation (handle,0); 
v_show_c (handle); 
button_wait(); 

} 


draw menu () 

{ 

int height; 

v_hide_c (handle); 
v_clrwk(handle); 
draw_rec (reel,GREEN,SOLID,0); 
draw_rec (rec2,BLACK,HOLLOW,0); 
v_pline (handle,2,linel); 
v_pline (handle,2,line2); 

vst height (handle,10,&dummy,Sdummy,Sdummy,Sdummy); 

vst color (handle,RED); 

vst effects (handle,NORMAL); 

v_gtext (handle,110+152*t factor,72*v_factor, "EFFECTS" ); 
v gtext (handle,116+152*t factor,104*v_factor, "HEIGHT") ; 
v_gtext (handle,116+152*t factor,136*v_factor, "ROTATE" ); 
v_show_c (handle); 

} 
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draw_rec(rec,fcolr,inter, style) 
int rec[]; 

int fcolr,inter,style; 

{ 

int rxc[4]; 
int x; 

for (x=0; x<4; ++x) 

rxc[x] = rec[x]; 
vsf color(handle,fcolr); 
vsf interior(handle,inter); 
vsf_style(handle,style); 
v bar(handle,rxc); 

} 

open vwork() 

{ 

int i; 

handle = graf handle(Sdummy,Sdummy,Sdummy,Sdummy); 
for (i=0; i<10; work in[i++] = 1); 
work in[10] = 2; 

v_opnvwk (work in, Shandle, work out); 

} 

init() 

{ 

int x; 


case 


case 


case 


} 


res = Getrez(); 
switch (res) { 

0 : 


h_ 

factor = 

1; 

V 

factor = 

1; 

t 

factor = 

0; 

break; 


h_ 

factor = 

2; 

V 

factor = 

1; 

t 

factor = 

1; 

break; 

i . 


h_ 

factor = 

2; 

V 

factor = 

2; 

t 

factor = 

1; 


for (x=0; x<4; ++x) 


== 0 

1 

X == 2) { 



reel [ 

x] 

= reel[x] * 

h 

factor; 

rec2 [ 

x] 

= rec2[x] * 

h 

factor; 

linel 

[X] 

= linel[x] 

■k 

h factor; 

line2 

[X] 

= line2[x] 

■k 

h factor; 


else { 


reel[x] 

= reel[x] * 

V 

factor; 

rec2[x] 

= rec2[x] * 

V 

factor; 

linel[x] 

= linel[x] 

•k 

v factor; 

line2[x] 

= line2[x] 

k 

v factor; 


} 

graf mouse (HAND,mouse^form); 
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button_wait() 

{ 

int button, mx, my; 

button = 0; 

while (button == 0) 

vq_mouse(handle,Sbutton,&mx,&my); 
while (button > 0) 

vq_mouse(handle,Sbutton,&mx,&my); 

} 

mouse_print(mx,my) 
int mx, my; 

{ 

char tx[5], ty[5]; 

vst height (handle,6,Sdummy,Sdummy,Sdummy,Sdummy); 

sprintf(tx, "%d ",mx); 

sprintf(ty, "%d ",my); 

v_gtext(handle,20,30,tx); 

v_gtext(handle,52,30,ty); 

} 
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CHAPTER 12 - ALERT BOXES AND CUSTOM MOUSE FORMS 


We've spent the last couple of chapters examining GEM's VDI. We didn't cover everything, but we 
managed to touch upon most of the major functions. Some of the ones we glossed over are easy 
enough to figure out from the documentation supplied with your compiler; others, we'll get to as we 
need them, particularly the raster functions. 

In this chapter, we'll get started with GEM's AES (Application Environment Services). We'll learn how 
to create GEM alert boxes, a little about the interaction of the AES with the VDI, and how to define 
our own mouse forms. 

Getting to Work 

When you run this chapter's program, you'll be presented with an alert box like the one shown in 
Figure 1. Use the mouse to click on the first button (the one labeled "New"). The screen will clear, 
and the mouse pointer will change to a custom form. (You may have seen this cursor before. I used it 
in Moonlord ST, a game that was published some time ago in ST-Log.) Clicking the left button will 
return you to the alert box. 

Now, click the button labeled "System." The mouse form will change to one of the system cursors, 
the pointing finger. The last button is self-explanatory (I hope). 



A Small Matter of Incompatibility 

Before we get started with the nitty-gritty material, there's something you should be aware of 
whenever you're going to use AES or VDI mouse routines. The AES has close ties with the VDI; in fact, 
it relies on the VDI to do much of the dirty work. For instance, when you call the AES window¬ 
drawing functions, the window is created, in part, using VDI graphics. That's why some of the VDI 
routines are referred to as "graphics primitives." They're the foundation upon which all the 
sophisticated ST graphics are built. The VDI is, in a way, a subordinate of the AES. 

In most cases, when dealing with graphics, there's no problem with this hierarchy, but when you 
start handling mouse events (a fancy name for mouse input), it's easy to confuse the AES. Basically, 
you can use the mouse-handling routines in the AES or in the VDI, but not both at the same time. If 
you want to be on the safe side, use only the AES mouse functions. 

That's why button_wait() in Listing 1, a function that appeared in a different form in Chapter 11, had 
to be modified, replacing the VDI calls in the original with the AES calls found in this chapter's 
version. The AES alert box routines must, obviously, also handle the mouse. If we tried to use the VDI 
mouse routines, we'd have trouble. (Try it if you like; replace the new button_wait() with the old one. 
Then, if you leave the mouse in one place when clicking on a button, you'll find that the mouse will 
reclick the alert box with no help from you). If you look at button_wait(), you'll see that we've 
replaced the VDI call vq_mouse() with an AES call, evnt_button(). 

The function evnt_button() is a higher-level call and, as a result, is more complicated and flexible. 
When called, the function waits for a mouse button to be pressed. The call looks like this: 
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n_times = evnt_button(n_clicks,btn,state,&mx,&my,&ex_state,&k_state); 

All the parameters, including the return parameter, are integers or pointers to integers, and are 
described here: 

n_times The number of times the button attained the desired state. 

n_clicks The number of times the button must be clicked. 

button The button (left or right) which must be clicked. A value ofl 

indicates the left button, a value of 2, the right. 

state The state the mouse button must attain. A value of 0 is up, and a 

value of 1 is down. 

mx The X-coordinate of the mouse when the button event occurred. 

my The Y-coordinate of the mouse when the button event occurred. 

ex_state The state of the mouse buttons after exiting the function. 

k_state The keyboard's state after exiting the function. 

The valuesl, 2, 4 or 8 indicate that the right shift, left shift, control 
key or alternate key were pressed, respectively. 

As you can see, this call is more complicated than our old friend vq_mouse(), but allows us more 
options. 

Alert Boxes 

The alert box is the simplest of GEM's form library to use, since the system handles virtually 
everything for you. All you need to do is provide the proper information for the function call. To draw 
an alert box: 

choice = form alert(defIt,string); 

Here, choice is the button number pressed (returned from the function), deflt is the number of the 
default button (the button, if any, that will respond to the Return key), and string is a pointer to a 
string containing the alert box description. You may also use a string literal for the second parameter, 
by enclosing it in quotes. In fact, it's done that way in the sample program. 

The alert box description contains all the information GEM needs to draw your box: the icon that will 
be displayed, and the text for both the box and the buttons. The string actually has three segments 
separated by square brackets: 

[icon #][box text][button text] 

The icon # is the number of the icon you wish displayed, defined as follows (a value of 0 will not 
display an icon): 

♦ V 

12 3 

The text for the box may be up to thirty-two characters per line, with a maximum of five lines. How 
does GEM know where to divide the text? We tell it, by placing an OR symbol between each line: 
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[linel|line2|line3|line4|line5] 

Each alert box you design must have at least one button, but you may have up to three. The 
information for the buttons comes after the box text and consists of the text to be printed within 
each button. The buttons' texts are placed between square brackets, with each buttons' text 
separated by an OR symbol: 

[buttonl|button2|button3] 

The text for each exit button must be less than twenty characters. You can see the completed string 
in this chapter's sample program in the function do_alert(), found about halfway down the listing. 
Notice that, due to the length of the string, it had to be wrapped around to the next line. Normally, 
you can't divide a string, but by using a backslash (at the end of the first portion of the string), we can 
get around that limitation. When the C preprocessor sees the backslash, it knows that the rest of the 
string will begin at the left margin of the next line. If you want to use a backslash within a string, you 
must type two. 

They Don't Fit! 

When the form_alert() function is called, it uses the information you've supplied to figure out the 
number of buttons and the size of the box. Almost everything is taken care of for you, but you may 
find it necessary to "clean up" the box description a bit, in order to force GEM to do exactly what you 
want. 

For instance, the number of buttons that will fit in the box is largely dependent on the length of the 
text and the size of the icon (if any) printed in the box. If the resultant alert box is only slightly 
smaller than the space needed for the buttons, GEM will place the buttons so that they overlap the 
box's borders. This type of box is not particularly attractive but will be fully functional. If the box is 
significantly undersized, GEM will start leaving buttons out, and you can't live with that. 

These problems don't usually crop up with single-button alert boxes (unless the button text is 
unusually long), but when you start dealing with three exit buttons, the glitches will likely introduce 
themselves. 

How can we force GEM to do what we want? Remember that the size of the box is dependent on the 
length of the text lines and the size of the icon, while the size of the buttons is dependent on the text 
printed within them. The icon size is unchangeable; it's set by the system, and the only way we can 
manipulate the icon is either to print it or not. But the box text and button text is fully under our 
control. 

One way, then, to help fit the required buttons into the box is to shorten the text within them. If the 
button text is just the way we want it, and we still can't fit all the buttons, we have to resort to the 
second method: padding the beginning or end of the box text with spaces. This will force GEM to 
draw the box larger. You can see an example of this in the form_alert() call in Listing 1. Try removing 
the additional spaces and recompiling the program. You'll find that, in medium resolution, the left¬ 
most button will overlap the box's border; in low resolution, the button is missing. 

Custom Mice 

GEM provides us with a number of built-in mouse forms, but we may sometimes find a need for 
something better suited to our application. When this occurs, graf_mouse() comes to the rescue. We 
discussed this function in Chapter 11, but didn't cover the method for designing custom mouse 
forms. Now, you'll be pleased to know, we're going to make up for that lack. 
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A mouse form is actually two graphics, 16x16 pixels in size, placed one on top of the other. The first 
graphic is the shape of the pointer itself. The second is the pointer's mask, which enhances its 
visibility. If you examine a mouse form, you'll notice that there's a one-pixel wide border around it. 
The border is a different color so that the mouse pointer won't "vanish" if it should be moved over 
something of the same hue. This border is the mask. 

The first step in designing a mouse form is to draw the form and its associated mask on a sheet of 
graph paper, each within a 16x16 grid. We must then translate the graphics to something the 
computer can understand. 

Our C program is going to need the data for the new form in some sort of numerical notation. 
Hexadecimal notation is best for our purposes, if for no other reason than the ease with which it's 
calculated from the binary representation of our graphics. If you don't know how to make these 
conversions, I suggest you go to your local library or bookstore for something which explains binary 
to hexadecimal conversions. 

The binary version of our graphic is simple enough to explain, though. Each grid location not filled in 
is an "off" bit; the others are "on." Each of these bits is represented in binary, by a 0 for off oral for 
on. Figures 2 and 3 illustrate the conversion of our custom pointer from its graphic state to 
hexadecimal. 


Coding It 

Once we've done the conversion, we must incorporate the result into our program. The easiest way 
to do this is to storethe data for the form and its mask in two integer arrays. If you look at the sample 
listing, you'll see our custom mouse pointer in the arrays mouse_data[] and mouse_mask[]. The "Ox" 
preceding each value tells the 
compiler that the number should be 
interpreted as hexadecimal. 

Just above the mouse form data in 
the sample listing is the declaration 
for a structure named mfrmstr 
(mouse form structure). To be more 
precise, it's not a structure 
declaration, but the declaration of a 
new data type consisting of a 
structure. We've defined this new 
data type by prefacing the structure 
definition with the C keyword 
typedef. Right below the declaration 
is where the actual structure 
variable, mouse, is declared. 

This structure will hold all the 
information GEM needs to enable 
our new mouse form. As you can see, 
the block contains 37 words of 
information. The first two words will 
hold the X- and Y-coordinates of the 
form's "hot spot." (Sounds pretty 
sleazy, doesn't it?) This is the location 
within the form which determines 
the X- and Y-coordinates for the 

entire mouse cursor. The third word will contain the number of bit planes. For high, medium, and 
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low resolutions, this value will be 1, 2, and 4, respectively. The fourth word will indicate what color 
the mouse form should be, and the fifth word will hold the color for the mask. The next thirty-two 
words are storage for the actual mouse form data. We'll move the values found in the arrays 
mouse_data[] and mouse_mask[] into these locations. 

To change the mouse form now, all we need do is fill in each member of the structure with the 
appropriate information and perform the following call: 

graf_mouse(255,Smouse); 

We went over this function in Chapter 11. What's important here, is that the parameter 255 tells 
GEM that we want to change to a user-defined mouse form. The parameter &mouse is the address 
of the block of data containing the form's description. 

Mission Accomplished 

There you have it: everything you need to know, to get the most out of alert boxes and to design 
your own mouse forms. As soon as you tear your eyes from this page, yank out your C compiler and 
fool around with the form_alert() function. Try different combinations of text and buttons, until you 
feel comfortable with the function. Then, design some alternate mouse pointers and modify Listing 1 
(or write your own code from scratch; that's really the best way to learn) to install your new forms. 
How about changing Listing 1, so the alert box buttons allow you to alternate between two custom 
mouse forms? That will mean having two sets of data, one for each form, and changing the 
new_mouse() function so you can pass it the address of the form description for the cursor you want 
to implement. 
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Program Listing #1 

j •k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k J 

/* C-MANSHIP, Listing 1 */ 

/* CHAPTER 12 */ 

/* Developed with Megamax C */ 

J •k'k-k-k-k-k-k-k-k'k-k'k-k-k-k-k-k-k-k'k-k'k-k'k-k'k-k'k-k-k'k-k'k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k'k-k'k-k'k-k-k j 

#define TRUE 1 
#define FALSE 0 
#define FINGER 3 

/* Required GEM global arrays */ 

int work in [ 11], 

work_out[57], 

pxyarray[10], 

contrl[12], 

intin [12 8], 

ptsin[128], 

intout[128], 

ptsout[128]; 

/* A couple of global int variables */ 
int handle, dum; 

/* Mouse form definition block */ 
typedef struct mfrmstr 
{ 

intx hot; /* x-coordinate of pointer hot spot. */ 

inty^hot; /* y-coordinate of pointer hot spot. */ 


intplanes; /* number of bit planes. */ 

intfg_color; /* mouse form color. */ 

intbg_color; /* mouse mask color. */ 

intmask[16]; /* Data for mouse mask. */ 

intdata[16]; /* Data for mouse form. */ 

] MOUSEFORM; 

MOUSEFORM mouse; 


/* Data for the new mouse form */ 

int mouse_data[] = {0x0000,0x07C0,OxOFEO,0x1930, 

0x3118,0x6100,0x600C,0x7C7C, 

0x600C,0x610C, 0x3118,0x1930, 

OxOFEO,0x07C0,0x0000,0x0000 } ; 

int mouse mask[] = {0x07C0,0x0820,0x1010,0x26C8, 
0x4AA4,0x9292,0x9D72,0x8282, 

0x9D72,0x92 92,0x4AA4,0x26C8, 
0x1010,0x0820,0x0700,0x0000}; 

main() /* Main program */ 

{ 

appl_init(); /* Initialize our application. */ 

open vwork(); /* Go set up our workstation. */ 

do_alert(); /* Go to the main loop. */ 

appl_exit(); /* Back to the desktop. */ 

} 

open_vwork() /* Initialize a virtual workstation */ 

{ 

int i; 

handle = graf handle(&dum,&dum,&dum,&dum); 
for (i=0; i<10; work in[i++] = 1); 
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work in[10] = 2; 

v__opnvwk (work in, &handle, work-out) ; 


do alert() /* This is the main loop. It calls the alert box */ 
{ /* function and the functions to change the mouse */ 

/* form. The loop repeats until REPEAT == false. */ 


int choice, 
repeat, 
deflt; 


/* Will hold button choice. */ 
/* Loop control variable. */ 
/* Holds default button choice. */ 


*/ 


} 


repeat = TRUE; /* We set this so the loop will repeat. */ 

deflt = 3; /* Set default button to Quit (see below). */ 

while (repeat) { 

choice = form alert (deflt, 

"[1][ _ MOUSE FORM DEMO | C-manship|\ 

Chapter Twelve][New | System | Quit ]") ; /* Draw alert box. */ 
if (choice == 1) { /* CHOICE contains the button pressed. */ 

new mouse(); /* If button was NEW, show new form. */ 

button_wait(); 

deflt = 2; /* Change default button to 2. */ 

} 

if (choice == 2) { /* If the second button was pressed, */ 

graf mouse (FINGER,&dum); /* then change to Hand icon. */ 
button_wait(); 

deflt = 1; /* Change default button to 1. */ 

} 

if (choice == 3) 

repeat = FALSE; /* When REPEAT == false (0), we get out 


} 


/* of the while loop and go to main(). */ 


new_mouse() /* Changes mouse form to the user-defined form */ 

{ /* found in the global arrays at top of listing */ 

int x; 


} 


mouse.x_hot = 8; 
mouse.y_hot = 8; 
mouse.planes = 4; 
mouse.fg_color = 0; 
mouse.bg_color = 2; 
for (x=0; x<16; ++x) 
mouse.mask[x] 
mouse.data[x] 


/* These two assignments set "hot spot" */ 
/* to the center of the mouse form. */ 

/* Set to 1 for high res and 2 for med. */ 
/* Mouse form drawn with color 0. */ 

/* Mouse mask drawn in color 2. */ 

{ /* This loop moves the data from */ 

= mouse mask[x]; /* global arrays into the 
= mouse data[x]; /* mouse form def'n block 


} 

graf mouse(255,Smouse); /* Presto! Our new mouse lives. */ 


*/ 

*/ 


button_wait() /* Waits for left button to be pressed and released. */ 

{ 

int dum; 


evnt_button(1,1,1,&dum,&dum,&dum,&dum); 
evnt_button(1,1,0,&dum,&dum,&dum,&dum); 
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CHAPTER 13 - THE FILE SELECTOR AND RASTER OPERATIONS 


As I Mentioned Before, GEM's AES contains a number of libraries, one of which is the form library. In 
Chapter 12, we were briefly exposed to the form library when we learned how to handle alert boxes, 
the simplest of the ready-to-use forms. However, most of the forms you'll employ once you get used 
to programming with GEM will be dialog boxes. 

Dialog boxes are complex and can be put together in almost any form imaginable. In an upcoming 
chapter, we'll sit down and have a long talk about these puzzling creatures, but for now, there's still 
one other ready-to-use form that we haven't explored yet: the file selector. 
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FIGURE 1 - The File Selector Box 

At first glance, one might think the file selector is difficult to handle (from a programmer's point of 
view), what with those slider bars and the editable text fields, and the exit buttons. The truth is that 
file selectors aren't much more difficult to program than alert boxes, because, just as with alert 
boxes, GEM handles much of the busy work for us. 

Picking a File 

Listing 1 shows how to use a file selector within a C program. When you run the program, you'll be 
presented with a file selector that looks something like Figure 1 (unless, of course, you've got one of 
those fancy file selector replacements in your AUTO folder). Choose one of the files. Then press an 
exit button. The file selector will be replaced with two lines of text showing the chosen file and the 
exit button you clicked. 

At this point, you're probably a little fuzzy on exactly what a file selector does for you. What kind of 
information does it return? Even though the file selector looks complicated, and allows the user to 
fiddle with scroll bars and buttons and text fields, all it really does is return a filename and the 
number of the exit button pressed. It's up to the programmer to decide what to do with the 
information. In most cases, the user will be selecting a data file -- such as a document for a word 
processor — and we'll use the filename returned to open that file and read the data into the program. 

Calling Up a File Selector 

One simple call will get the file selector box up on your screen: 

fsel_input (path,file,Sbutton); 

But there's a bit of preparation that must be done first. In the above function call, path is a pointer to 
a string in which the default pathname is stored, and file is a pointer to a string containing the default 


Port: FlYPertext by Lonny Pursell & PDF by DrCoolZic (jig) - VI.0 Oct. 2010 


Page 115/321 



































C-MANSHIP COMPLETE - by CLAYTON WALNUT 


filename (the text field to the center right of the box). The integer button will contain the value of 
the exit button chosen, where 0 equals the cancel button and 1 equals the OK button. 

The pointers path and file actually serve a dual purpose. Both of the text fields they represent are 
editable. Upon exit from the selector, they'll contain the strings typed by the user (if nothing was 
typed, they'll still contain whatever you put there). This is how we can find the file or path the user 
selected. 

But there are still a couple of things you need to know before you can start using file selectors. For 
instance, how are the strings pointed to by path and file formatted? The answer can be found in the 
function sel_file() in Listing 1. 

File Selector Housekeeping 

The first thing we must do in sel_file() is declare the variables we need and set aside some space for 
filenames. It's important that you reserve enough memory. Otherwise, strings typed by the user may 
overrun their allotment and tromp over other data. The storage area for the default pathname, 
path[50], is probably larger than we'll need, but it's better to be safe. 

Let's see what might happen if the array were smaller, say only 20 bytes (path[20]). Now, what if the 
file the user wants to select is found buried within two folders? We could end up with a pathname 
like: 


A: \FOLDER.ONE\FOLDER.TWO\FILENAME.EXT 

That gives us a pathname that's 37 bytes long. Our storage area will hold only twenty characters. 
Watch out for that. 

The storage for the default filename, file[13], isn't as tricky, since no filename will ever exceed 
thirteen characters (including the \0 terminator). 

After we've set up our variables and storage space, we must do some initialization. First, we fill the 
default path and filename areas with nulls, getting rid of all the junk. We then ask the system for the 
default drive (the one the program was loaded from; any filename that doesn't specify a drive will 
use the default), convert it to ASCII, and store it in the first element of path[] with the line: 

path[0] = DgetdrvO + 65; 

DgetdrvQ is a GEM DOS call (gemdos(0xl9) for those who are interested) and returns the number of 
the default drive as an integer where 0 means drive A, 1 means drive B, and so on. Since our 
pathname must be a string, we need to convert the drive number to the ASCII equivalent. And what's 
ASCII for A? Sixty-five, right? So all we have to do is add 65 to the drive number, then place this value 
in the first element of our string, and we're on our way to creating the default pathname. 

We finish our pathname with the statement: 

strcpy (&path[1],":\*.*"); 

The function strcpyQ copies the string (including the null) pointed to by the second argument to the 
string pointed to by the first argument. In the example above, the colon will be copied into the 
second element of our pathname, with the rest of the characters in the string literal following. This is 
just one of many handy string-handling functions available with Megamax C. 

Other string-handling functions include strcat() and strncatQ which concatenate strings; strcmp() and 
strncmpO which compare strings; strlenQ which returns the number of characters in a string; and 
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index() and rindex() which return a pointer to the first or last occurrence of a character in a string, 
respectively. The details of these functions can be found in your compiler manual. 

Finally, in sel_file() we open the file selector, then print the results of the user's selections. 

Now that we've got the file selector mastered, let's move on to something really challenging. 

Raster Operations 

Many of you may have heard the term Bit Block Transfer, or BITBLT as it's more commonly known. 
This is the name sometimes given to the VDI's raster operations. What's a raster operation? Simply, 
it's the movement of blocks of memory, usually from screen memory to someplace else in RAM or 
vice versa. Many of the programming techniques you'll be learning will require a good knowledge of 
raster operations. Rastering is used to draw icons and sprites, and also to update windows. 

GEM's VDI contains a number of functions that help the programmer perform this memory juggling, 
but in order to take advantage of these functions, we must first have a way to describe the blocks of 
memory we want to move. We supply this information with a Memory Form Definition Block 
(MFDB). 

The MFDB consists of ten words of information: the address of the memory we want to move; its 
height and width; the coordinate system we're using (raster or normalized); and the number of bit 
planes that make up our screen. (There are also several words that, although ignored, must be 
present.) 

C provides a handy way to group this information into a single unit: the structure. Our MFDB, then, 
looks something like this: 

typedef struct mfrmblk { 
long f_addr; 
int f w; 
int f h; 
int f wdwidth; 
int f^stand; 
int f nplanes; 
int f_rl,f r2,f r3; 

} MFDB; 

Here, f_addr is the address of the memory block, f_w and f_h are the width and height of the block in 
pixels, f_wdwidth is the width of the block in words, f_stand is the coordinate system (0 for raster, 1 
for normalized), and f_nplanes is the number of bit planes. The integers f_rl, f_r2 and f_r3 are 
reserved for future use and may be ignored (I usually set them to 0 just to be safe). 

Filling in the Blanks 

Confused yet? I thought you might be. All this talk of coordinate systems and bit planes can be -- if 
you've never been exposed to it before -- daunting. Bit planes were mentioned in Chapter 12, when 
we designed our own mouse forms, but now it's time to learn a little more about the way your ST's 
screen memory works. 

The ST reserves 32K of memory for the screen, no matter what resolution you're in. In high 
resolution, the organization of this memory is simple: each bit in memory represents one pixel on the 
screen. 

The first 640 bits (80 bytes) represent the first row of the screen; the second 640 bits represent the 
second row of the screen; and so on, for 400 rows. If we multiply 80 bytes per row times 400 rows, 
we get the magical number 32,000, the size of screen memory. If a bit is on, the corresponding pixel 
will be a black dot; if a bit is off, the pixel will be white. 
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When we talk about low or medium resolution, however, we throw in an extra complication: color. 
Now, we have to know more than just whether a pixel is on or off; we need to know its color. And we 
still need to get all this information into 32K. 

In medium resolution, we're allowed four colors. It takes two bits to store this information (four 
possible combinations: 00, 01,10, 11) versus the one bit needed to represent black and white, which 
means 32K of screen memory can hold only enough information for 128,000 pixels instead of the 
256,000 pixels we had in monochrome. (Wow! A quarter of a million!) In order to compensate for 
this, the designers of the ST decided to halve the vertical resolution, giving us a screen 640x200. 
Eighty bytes (640 bits) times 200 lines times two bit planes per pixel gives us a total screen memory 
of 32K. 

In low resolution, we have 16 colors to work with. Since it takes four bits to represent 16 
combinations, we find that we must again cut the number of pixels in half, to 64,000. This time, the 
ST's designers made up the difference by halving the horizontal resolution and the vertical resolution 
(as compared to high resolution), to give us a screen 320x200. 

That's not the end of the story. In the color modes, the screen memory is divided into bit planes (see 
Figure 2). You can think of the bit planes as transparencies laid one on top of the other. In order to 
get the color value for the first pixel on the screen, you must combine the first bit of each plane. The 
second bit of each plane forms the color value for the second pixel; the third for the third; etc. In 
medium resolution, there are two bit planes. In low, there are four. 
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FIGURE 2 - Bit planes for low resolution 


Now that we understand (yeah, right) all this nonsense about bit planes, what's with these 
coordinate systems? When programming in GEM, there are two coordinate systems you may choose 
between when you open a new workstation: Normalized Device Coordinates (NDC) or Raster 
Coordinates (RC). 

The NDC system divides the screen into a grid that's 32,768x32,768 with the origin (point 0,0) in the 
lower-left corner. Moving to the right from the origin increases the value of the X-coordinate, while 
moving upward from the origin increases the value of the Y-coordinate. 

The RC system is the one we usually use on the ST, where the origin is in the upper-left corner of the 
screen, and the width and height of the screen depend on the current resolution. The sample 
program (Listing 2) uses the RC system. 

The Next Listing 

When you compile and run Listing 2, the infamous ANALOG "A" (in multicolors) will appear. Use the 
mouse to point and click anywhere on the screen. The "A" will move to that location. When you're 
through, press the right mouse button to return to the desktop. 
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The "A" that you've been moving around the screen is an example of an icon, and is an image we've 
stored in memory. An icon is usually designed by drawing it with a graphics program, such as 
NeoChrome or DEGAS, then converting the image to its hexadecimal equivalent. This can be a 
complicated procedure, especially if you're dealing with a color mode and all those bit planes. Your 
best bet is to get hold of one of the public domain icon editors floating around. At any rate, the icon 
editor will take the image you've created and convert it to data which can be merged with your 
source code. 

Take a look at Listing 2. About a third of the way down, you'll find the array, icon[]. See all that data? 
That's the hexadecimal representation of our ANALOG icon as it appears in low resolution 
(remember — four bit planes). The data would look different in medium or high resolution, because 
we wouldn't be dealing with as many bit planes. In fact, in high resolution, there would be only one- 
fourth as much data, since there would be no colors to keep track of. 

Now, take a look at the function do_icon(), where the main logic for the demo program is found. 

First, we change the mouse form to the pointing finger and initialize some variables. Then, after 
setting our control variable, repeat, to true, we enter the main while loop. 

Once in the loop, we adjust the mouse coordinates (X and Y) so the icon will be drawn in the right 
place. We have to do this, because the coordinates we get from the mouse are the location of the 
mouse's hot spot (oooh, I love it when we talk dirty); the coordinates we need for the raster 
functions are the upper-left and lower-right corners (actually, any diagonally opposed corners) of the 
block of screen memory. If we didn't do this extra calculation, the icon would always be drawn below 
and to the right of the mouse pointer. 

We then save the coordinates so that when we get a new mouse X and Y, we will be able to erase the 
first drawing. Finally, we turn off the mouse and call the function draw_icon() to actually draw the 
icon on the screen. 

The Raster Details 

Which brings us to the point of this lengthy discussion (you knew there had to be a point, right?): the 
VDI call vro_cpyfm(). This function actually performs the rastering (there's a second VDI raster 
function, vrt_cpyfm(), which is very similar except that it's used to copy forms designed for 
monochrome onto a color screen). The function is called like this: 

vro cpyfm(handle,mode,pxy,Smfdbl,&mfdb2); 

Here, the integer handle is the handle returned when we opened the virtual workstation; the integer 
mode is the raster writing mode; the pointer pxy is the address of an array of integers describing 
coordinates of the two rectangles; and &mfdbl and &mfdb2 are pointers to the two MFDBs that 
describe the areas to be rastered. Gasp! 

The parameter mode can be any number from 0 to 15. The writing mode is the logical operation 
that's used to combine the source and destination values. There are 16 logical operations available to 
us. In the sample program, we're exclusive ORing the source and destination. This way, an image can 
be easily erased by redrawing it in the same (exclusive OR) mode. The disadvantage to this mode is 
that, if we're not working with a blank screen, our image will be transparent, allowing the 
background to bleed through. 

I'm not going to spend a lot of time describing the different writing modes. You should look them up 
in your manual or experiment with them. You'll probably find that there are only a couple you'll use; 
the rest are there should you need them. 

The pxy array holds our rectangles' coordinates: the upper-left and lower-right corners of both the 
source and destination rectangles. They should be stored in this order: 
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sxl,syl,sx2,sy2,dxl,dyl,dx2,dy2 

Now that we understand the vro_cpyfm() call, let's take a look at draw_icon() for the details. First, 
we must initialize the two MFDBs. We don't have to talk much about this, since the MFDBs are fairly 
well described above. However, there are a couple of things that should be clarified. 

For one thing, if you look at the data for the icon in the source code, it would appear to be 6 long 
words wide or 192 bits — a big icon! Now, anyone who can tell me why our data is 192 bits wide, 
raise your hand. Those of you who are slinking down under your desks in embarrassment can relax; 
I'm not going to call on you. But do the words "bit planes" jar any memories? 

"Yes!" you say. "Yes! That's why we've got 192 bits. We're dealing with 4 bit planes, and 192 divided 
by four is...is...is..." 

Forty-eight. 

"Yeah...thanks." 

You're welcome. Now you know why we've made icn_w equal to 48 instead of 192. But here's 
another question for you: How come the icon, when it's on the screen, appears only 23 pixels wide? 

"I don't know," you mumble, climbing back under your desk. 

Well, climb back into the light, my friend; it's not your fault that you can't answer the last question. 
There's something I haven't told you. Because of the way the raster functions move data, the width 
of a data block must be a multiple of 16 (this allows more efficient movement of data). In the case of 
our "A" icon, we've had to pad the left and right of the image with "off bits" in order to bring the 
width up to the next highest multiple of 16 which is, of course, 48. 

Now, we get to the screen MFDB. If you look at draw_icon(), you'll see that each member of the 
icon's MFDB, s_m, had to be initialized properly. Yet, for the screen MFDB, scr_m, we've only one line 
of code: 


scr m.F addr = OL; 

Why? Whenever the form address element (f_addr) of the MFDB is set to 0, the system knows it will 
be dealing with the screen and will automatically handle everything for you. You don't have to fill in 
the rest of the MFDB. You can if you want, but, unless you're the type of person who enjoys painting 
houses with a hair, why bother? 

Off Again 

I know I say this at the end of just about every chapter, but I'm going to say it again: practice! 
Everything you're learning builds upon what has gone before. Just like a course in mathematics, if 
you miss a lesson or don't understand it completely, you'll get more and more confused as you try to 
go on. 

Try designing your own icons and raster them to the screen, experimenting with the different writing 
modes to see the results (there's an excellent illustration of the 16 modes on page 228 of the 
Programmer's Guide to GEM, published by Sybex, for those of you who have that book). Of course, in 
order to experiment with the writing modes, you're going to need some sort of graphic in the 
background. Looks like you'll be getting some more practice with the VDI, eh? 
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Program Listing #1 

j •k******************************************************** J 

/* C-MANSHIP, Listing 1 */ 

/* CHAPTER 13 */ 

/* Developed with Megamax C */ 

f*********************************************************J 

#include <osbind.h> 

/* The usual required GEM global arrays */ 
int work in [ 11], 
work-out[57] , 
pxyarray[10], 
contrl[12], 
intin[128], 
ptsin[128], 
intout[128], 
ptsout[128]; 

/* Global variables */ 
int handle, dum; 

/* Main program */ 
main () 

{ 

appl_init (); 
open vwork (); 
selfile (); 
button_wait (); 
v_clsvwk (handle); 
appl_exit (); 

} 

/* Initialize a virtual worksation. */ 
open^vwork () 

{ 

int i; 

handle = graf handle (&dum,&dum,&dum,&dum); /* Get handle. */ 
for (i=0; i<10; work in[i++] = 1); /* Init GEM arrays. */ 
work in[10] = 2; 

v_opnvwk (work-in, Shandle, work out); /* Open virtual 

workstation. 

*/ 

} 


/* Do file selector box. */ 
sel_file () 

{ 

int button, /* File selector button value. 

i; /* Loop variable, 

char path[50], /* Storage for filenames, 
file [13] ; 

for (i=0; i<20; path[i++] = '\0 ' ) ; /* Fill filename w/ nulls. */ 
for (i=0; i<13; file[i++] = '\0 ' ) ; 

path[0] = DgetdrvO +65; /* Make drive # a char. */ 



/* Initialize application. */ 
/* Set up workstation. */ 
/* Go select file. */ 
/* Wait for a mouse button press. */ 
/* Close virtual workstation. */ 
/* Back to the desktop. */ 
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strcpy (Spath[1], ":\*.*" ); /* Complete the pathname. */ 

fsel_input (path,file,Sbutton); /* Open file selector box. */ 

prnt_info (file,button); /* Go print results. */ 


/* Print out the user's choices. */ 
prnt info (file,button) 

char *file; /* Pointer to the chosen filename. */ 
int button; /* Value of the button pressed. */ 

{ 

v_gtext (handle,28,50, "The file you chose was: "); 
v_gtext (handle,220,50,file); 

v_gtext (handle,28,66, "And you pressed the "); 
if (button == 0) 

v_gtext (handle,188,66, "CANCEL button."); 

else 

v_gtext (handle,188,66, "OK button."); 


/* Waits for left button to be pressed and released. */ 
button_wait() 

{ 

evnt_button (1,1,1,&dum,&dum,&dum,&dum); 
evnt_button (1,1,0,&dum,&dum,&dum,&dum); 

} 


Program Listing #2 

j •k'k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k'k-k'k-k'k-k'k-k-k-k-k'k-k'k-k'k-k'k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k'k-k'k J 

/* C-MANSHIP, Listing 2 */ 

/* CHAPTER 13 */ 

/* Developed with Megamax C */ 

J •k'k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k'k-k'k-k'k-k'k-k-k'k-k'k-k'k-k'k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k'k-k'k-k-k J 


#include <osbind.h> 


#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 


S_XOR_D 6 
TRUE 1 
FALSE 0 
LEFT 1 
RIGHT 2 
HAND 3 
OFF 256 
ON 257 
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/* The required GEM global arrays */ 

int work in[11], 

work_out[57], 

pxyarray[10], 

contrl [ 12] , 

intin[128], 

ptsin [12 8] , 

intout [12 8] , 

ptsout[128]; 

/* Global variables */ 
int handle, dum; 

/* Memory Form Definition Block */ 
typedef struct mfrmblk { 


long 


f addr; 

/* 

Addr of form data. 


*/ 

int 

f 

w; 

/* 

Width of the form in 

pixels. 

*/ 

int 

f 

_h; 

/* 

Height of the form in 

i pixels. 

*/ 

int 

f 

wdwidth; 

/* 

Width of the form divided by 16. 

*/ 

int 

f 

stand; 

/* 

0 = raster (RC); 1 = 

normalized (NDC). 

*/ 

int 

f 

nplanes; 

/* 

Number of bit planes 

(1, 2 or 4). 

*/ 

int 

f 

rl; 

/* 

The last three words 

are reserved. 

*/ 


int f_r2; 
int f_r3; 

} MFDB; 

/* Data for the ANALOG "A" icon. */ 
long icon[] = { 

0x00000000,0x00000000,OxlFFFlFFF,OxlFFFlFFF,OxFOOOFOOO, OxFOOOFOOO, 
0x00000000,0x00000000,0x35552CCB,0x3C3823F8,0x58003800,0xF8000800, 
0x00000000,0x00000000,0x55554CCB,0x7C3843F8,0x58003800,OxF8000800, 
0x00000000,0x00000000,0xD555CCCB,0xBC38 83F8,0x58003800,0xF8000800, 
0x00010001,0x00010001,0x57FDCFFF,0x3FFC07FC,0x58003800,0xF8000800, 
0x00030002,0x00020002,0x5803C803,0x38020802,0x58003800,0xF8000800, 
0x00030002,0x00020002,0x5803C803,0x38020 802,0x58003800,0xF8000800, 
0x00030002,0x00020002,0x5403CC03,0x3C020402,0x58003800,0xF8000800, 
0x00030002,0x00020002,0x57F3CFF3,0x3FF207F2,0x58003800,0xF8000800, 
0x00030002,0x0002 0002,0x555BCCCB,0x3C3A03FA, 0x58003800,0xF8000800, 
0x00030002,0x0002 0002,0x555BCCCB,0x3C3A03FA, 0x58003800,0xF8000800, 
0x00030002,0x00020002,0x55F3CDF3,0x3DF203F2,0x58003800,0xF8000800, 
0x00030002,0x00020002,0x5503CD03,0x3D020302,0x58003800,0xF8000800, 
0x00030002,0x00020002,0x5583CC83,0x3C820382,0x58003800,0xF8000800, 
0x00030002,0x00020002,0x5583CC83,0x3C820382,0xF800F800,0xF800E800, 
0x00030002,0x00020002,0x5543CCC3,0x3C4203C2,0xF800F800,0xF800E800, 
0x00030002,0x00020002,0x5543CCC3,0x3C4203C2,0xF800F800,0xF800E800, 
0x00030002,0x00020002,0x5563CCE3,0x3C2203E2,0x58003800,0xF8000800, 
0x00010001,0x00010001,OxFFCIFFCl,OxFFCIFFCl,OxFOOOFOOO,OxFOOOFOOO 

} ; 

int icn_w = 48, /* Width of icon. */ 

icn h = 18; /* Height-1 of icon. */ 
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/* Main program. */ 
main () 

{ 

appl_init (); /* 

open_vwork (); /* 

graf_mouse (OFF,&dum); /* 
v_clrwk (handle); /* 

graf_mouse (ON,&dum); /* 

do_icon (); /* 

v_clsvwk (handle); /* 

appl__exit (); /* 

} 


Initialize application. */ 


Set up workstation. */ 
Shut off mouse. */ 
Clear the screen. */ 
Bring the critter back. */ 
Go draw icon. */ 
Close virtual workstation. */ 
Back to desktop. */ 


/* Initialize a virtual workstation. */ 
open vwork () 

{ 

int i; 


} 


handle = graf handle (&dum,&dum,&dum,&dum); /* Get handle. */ 
for (i=0; i<10; work in[i++] = 1); /* Init GEM arrays. */ 

work in[10] = 2; 

v opnvwk (work in, Shandle, work out); /* Open v. workstation. 

*/ 


/* Main program loop */ 
do_icon () 

{ 


int button, /* Mouse button pressed. */ 

x, /* Mouse X coordinate. */ 

y, /* Mouse Y coordinate. */ 

ox, /* Old Mouse X coordinate. */ 

oy, /* Old Mouse Y coordinate. */ 

repeat; /* Loop flag. */ 


graf mouse (HAND,&dum); 
x=50 ; y=50; 
repeat = TRUE; 
while (repeat) { 
x -= 30; y 
ox = x; oy 
graf mouse 
draw icon 


-= 20 ; 

= y; 

(OFF,&dum); 

(icon,S XOR D,icn w. 


/* Switch mouse forms. */ 

/* Init loc. of icon */ 

/* Get into WHILE loop. */ 

/* Begin WHILE loop. */ 

/* Adjust mouse coords */ 
/* Save old coords. */ 
/* Turn off mouse. */ 

/* Go draw icon. */ 


icn h,x,y,x+icn w,y+icn h) 
graf_mouse (ON,&dum); 
button = 0; 
while (button == 0) 


/* Turn on mouse. */ 

/* Get into WHILE loop. */ 
/* Begin WHILE loop. */ 


if 


vq_mouse (handle,Sbutton,&x,&y); /* Get mouse status. */ 
(button == LEFT) { /* If left button pushed... */ 

graf_mouse (OFF,&dum); /* Turn off mouse. */ 

draw icon (icon,S_XOR D,icn_w, /* Erase old icon. */ 

icn h,ox,oy,ox+icn w,oy+icn h); 
graf mouse (ON,&dum); /* Turn mouse back on. */ 


} 

if 


(button == RIGHT) 
repeat = FALSE; 


/* If right button pushed...*/ 

/* get out of loop. */ 
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/* Perform raster operation. */ 

draw_icon (data,mode,width,height,dxl, dyl, dx2, dy2) 
long data[]; 

int mode, /* Raster writing mode. */ 

/* Icon width. */ 

/* Icon height. */ 

/* Upper left X coordinate of dest'n 
/* Upper left Y coordinate of dest'n 
/* Lower right X coord of dest'n rectangle. 
/* Lower right Y coord of dest'n rectangle. 


width, 
height, 
dxl, 
dyl, 
dx2, 
dy2 ; 

{ 


rectangle. 
rectangle. 

*/ 
*/ 


MFDB s m, /* Form definition block for source. */ 
scr m; /* Form definition block for screen. */ 
int pxy[8]; /* Coords for source and dest'n rectangles. 


'/ 


s m 
s m 
s m 
s m 
s m 
s m 
s m 
scr 
pxy 
pxy 
pxy 
pxy 
pxy 
pxy 
pxy 
pxy 
vro 


.f_addr = (long) data; 

. f w = width; 

. f h = height; 

. f wdwidth = width/16; 

.f_stand = 0; 

.f nplanes = 4; 

.f rl = s_m.f_r2 = s m. 
m.f addr = 0; 


/* 

/* 


/* 

/* 

f r3 


0] 

1 ] 

2 ] 

3] 

4] 

5] 

6 ] 
7] 


0 ; 

0 ; 

width; 
height; 
dxl ; 
dyl; 
dx2 ; 
dy2 ; 


/* Upper 


/* 

/* 

/* 

/* 

/* 

/* 

/* 


Upper 

Lower 

Lower 

Upper 

Upper 

Lower 

Lower 


cpyfm(handle,mode,pxy. 


Put addr of icon data in MFDB */ 
Store width of icon in MFDB */ 

/* Store height of icon in MFDB */ 
/* Store icon width/16 in MFDB */ 
Raster coordinates. */ 

Low res (4 bit planes). */ 

= 0;/* Zero reserved words. */ 
/* Set up screen MFDB. */ 
left X coord of source block. */ 

left Y coord of source block. */ 

right X coord of source block. */ 

right Y coord of source block. */ 

left X coord of dest'n block. */ 

left Y coord of dest'n block. */ 

right X coord of dest'n block. */ 

right Y coord of dest'n block. */ 

&s m,Sscrm); /* Do the raster op. * 


/ 
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CHAPTER 14 - OBJECT TREES AND DIALOG BOXES 


Now that we know how to handle the two simplest of GEM's forms, the alert box and the file 
selector, it's time to move on to the granddaddy of them all: the dialog box. Because the dialog box is 
so versatile, we could discuss its uses endlessly and still not exhaust its possibilities. For that reason, 
this chapter's discussion should not be considered as a complete guide to dialog boxes, but only as 
an introduction. Once you understand the way dialogs work, the only limit will be your imagination. 

The Definitions 

Before we get into a detailed discussion of dialog boxes, we must first define a couple of terms: 
objects and trees. Objects are used to visually represent each item that makes up a dialog box. 
You've seen them hundreds of times: boxes and buttons and text strings. Each object has its own set 
of attributes that tailor it to the programmer's (and eventually, the user's) needs. 

From a programming point of view, an object is a data structure, the members of which describe the 
object, storing all the necessary information to bring that object up on the screen. 

The objects of a dialog box are connected in an object tree. A tree is a way to link items in a 
hierarchical manner. That is, there's one main item (the tree's root), which has connected to it other 
items (which, relative to the tree's root are called children, and relative to each other are called 
siblings). The children may also have children of their own (and thus become parents), and so on 
down the line, each new group of siblings subordinate to the ones that have gone before. 

An object tree is an array of objects, the attributes of which are stored in the previously mentioned 
data structure. Three elements of an object's data structure determine the way the object fits in with 
the rest of the tree. Specifically, each object contains, among other things, a pointer to the next 
sibling, a pointer to the first child (the head) and a pointer to the last child (the tail). 
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Figure 1 illustrates the principles of this type of tree structure, using a simple dialog box as an 
example. As you can see, even a simple dialog box has quite a maze of connections. Because of this 
complexity, few programmers bother to try and design dialog boxes from scratch. They instead use 
the resource construction program that came with their compiler. 


A SIMPLE DIALOG 


BUTTOH 1 I 

BUTTON 2 I 



FIGURE 1 - Tree Structure of a Dialog Box 


RCP: A Mini Tutorial 

Currently, the two most popular resource construction programs are the ones included with the Atari 
Developer's Kit and the Megamax C compiler. Since the programs in this column are developed with 
Megamax, we'll use the Megamax Resource Construction Program (RCP) to build our dialog box. If 
you're using the Atari Developer's Kit, don't fret; the Resource Construction Set (RCS) that came with 
your kit will work equally well for our purposes. The only difference is the operation of the programs. 

So, everybody load up their resource construction programs, and let's get busy. Figure 2 is the dialog 
box we'll be building. You should refer to this illustration as you construct your version. 
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ST 

LOC 


THIS IS A SAMPLE DIALOG BOX 


ST 

LOG 


RADIO BUTTONS 


tti 


#2 



«3 


#4 



#5 


#6 


NAME: 
AGE! __ 


OPTION 1 


OPTION 2 


0000 


0 


OK 


CANCEL 


FIGURE 2 


Once you have your resource construction program loaded, go to the File option of the menu bar and 
select New. A window titled NONAME will appear. To the left of this window are the types of 
resources we can build, represented in icon form. Place the mouse pointer over the dialog icon, press 
and hold down the left button, and drag the icon into the window. Release the button, and a dialog 
box will appear, asking you for the name of the new tree. Clear the NAME field by pressing Escape. 
Then type SAMPLE and press Return. 


Now double click the new dialog icon (the one you dragged to the window). This will open the dialog, 
presenting you with a "blank slate." The icons to the left will change to a dialog box "parts kit." The 
parts shown are icon representations of the types of objects you can use to build your dialog box. 


The types are are as fo 


lows: 


Button 

A box containing centered text 

String 

A line of text 

FText 

Formatted text 

FBoxText 

A box containing formatted text 

IBox 

An invisible graphic box 

Box 

A graphic box 

Text 

Graphic text 

BoxChar 

A graphic box enclosing a single character 

BoxText 

A graphic box enclosing text 

Icon 

Description of an icon 


Now let's start filling out our dialog box with objects. 


Crankin' with the RCP 

Step 1: Drag the STRING object onto your dialog box, and then double-clickit. A dialog box 

containing a number of attributes will appear. At the bottom will be a line labeled TEXT. 
Clear the line by pressing the escape key. Then enter (without the quotes) "THIS IS A 
SAMPLE DIALOG BOX," and press Return. Drag your new string to the top of the dialog box 
and center it, as shown in Figure 2. 

Step 2: Drag an ICON object onto your dialog box, and double-click it. Click the EDIT ICON button 
from the dialog box that appears, and draw the ST-Log icon (or any icon you like) with your 
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Step 3: 

Step 4: 

Step 5: 
Step 6: 


Step 7: 


Step 8: 


Step 9: 


Step 10: 


Step 11: 


Step 12: 


mouse. When complete, click the OK button. Drag the icon to the left of the text created in 
Step 1 and position it as shown in Figure 2. 

If the icon is not shown in inverse (selected), give it a single mouse click. When the icon is 
selected, type Control-C (copy), point the mouse to the right-hand side of your dialog box, 
and type Control-V (paste) twice (the first keystroke deselected the original icon). You 
should now have a duplicate of the first icon. Drag it into position, to the right of the string, 
as shown in Figure 2. 

Drag the BOX object (the empty rectangle) onto your dialog box. Place the mouse cursor on 
the lower-right corner of the box and, holding down the left button, stretch the box until 
it's about the same size as the box labeled RADIO BUTTONS in Figure 2. Position the box, 
and double-click it. An attribute dialog box will appear. Use the mouse to select the 
SHADOWED attribute. Then click the OK button. 

Using the same method as in Step 1, create a string that reads "RADIO BUTTONS," and 
position it at the top of the box created in Step 4. 

Drag a BUTTON object into the box created in Step 4, and double-click it. When the 
attribute dialog appears, select the following options: SELECTABLE, RADIO BUTN and 
TOUCHEXIT. (Note that sometimes an attribute - in this case, SELECTABLE - has already 
been activated for you.) Modify the text field to read "#1." Then click the OK button. While 
the radio button is still highlighted (shown in inverse), type Control-N, and name the object 
"RADIOl." Position this button in the upper left of the "Radio Button" box, beneath the 
string, as shown in Figure 2. 

Use the copy and paste functions (as in Step 2) to place another radio button to the right of 
the one created in Step 6. Change the button's text to read "#2" and change the object's 
name to "RADI02." 

Using the method in Step 7, create four buttons labeled "#3," "#4," "#5," and "#6," and 
name them "RADI03," "RADI04," "RADI05," and "RADI06," respectively. See Figure 2 for 
placement. 

Drag the EDIT:_(not the one surrounded by a box) object into your dialog box, and 

double click it. If it isn't already selected, turn on the EDITABLE option. Clear the PTMPLT 
field with the escape key, and then type "NAME:" followed by one space and 10 underline 
characters. Use the down arrow on your keyboard to move the text cursor to the PVALID 
field. Then press Escape to clear the field. Type "aaaaaaaaaa." Use the down arrow key to 
move the text cursor to the PTEXT field. Then backspace till you reach a tilde (~) character. 
Now type followed by nine spaces. Click the OK button. Then name the object "NAME." 
Position the object as shown in Figure 2. 

Drag a second EDIT:_object into your dialog box, and double-click it. Make sure the 

EDITABLE option is set. Change the PTMPLT field to "AGE:" followed by one space and two 
underlines. Change the PVALID field to "99." Move to the PTEXT field and backspace until 
you reach a tilde character. Then type followed by one space. Click the OK button, 
name the object "AGE," and then position it as shown in Figure 2. 

Drag another BUTTON object into your dialog box, and double-click it. Select the attributes 
SELECTABLE, SHADOWED and TOUCHEXIT. Change the button's text to "OPTION 1." Click 
the OK button, name the object "OPTION1," and position it as shown in Figure 2. 

Use the copy and paste functions to create a duplicate of the button created in Step 11. 
Change the button's text to "OPTION 2," name the object "OPTION2," and position it as 
shown in Figure 2. 
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Step 13: Drag the BOXTEXT object into your dialog box, and double-click it. Select the SHADOWED 

attribute. Clear the PTMPLT and PVALID fields (if necessary). Then change the PTEXT field to 
four spaces followed by four Os and four more spaces. Using the method shown in Step 4, 
stretch the box one segment higher (as you pull down on the mouse, the box will 
automatically "snap" to the next size). Name the object "NUMBERS," and position it as 
shown in Figure 2. 

Step 14: Drag another BOXTEXT icon onto your dialog box, and double-click it. Set the TOUCHEXIT 
option. Make sure the PTMPLT, PVALID and PTEXT fields are clear. Then, when positioned 
on the PTEXT field, hit space, Control-A, space (the keys, not the words). Resize the object 
as in Step 13, and name it "UPARROW." Position it on top of the box created in Step 13 as 
shown in Figure 2. 

Step 15: Use the copy and paste functions to create a duplicate of the UPARROW object. Then clear 
the PTEXT field and press space, Control-B, space. Name the object "DWNARROW." Then 
position it on top of the NUMBERS object as shown in Figure 2. 

Step 16: Drag another BUTTON object into your dialog box, and double-click it. Set the SELECTABLE, 
DEFAULT and TOUCHEXIT options. Change the text field to "OK." Resize and position the 
object as shown in Figure 2 and name it "OK." 

Step 17: Drag yet another button into your dialog box, and double-click it. Set the SELECTABLE and 
TOUCHEXIT options. Then change the TEXT field to "CANCEL." Resize and position the 
object as shown in Figure 2. Then name it "CANCEL." 

And that's it. You've just created your first dialog box. Now, to save all your hard work, close the 
dialog box by clicking on the upper-left corner of the window. Then select the SAVE AS option from 
the FILE menu. Name the file "SAMPLE," and you're on your way. To leave the RCP, select the Quit 
option from the File menu. 

You should now have three files on your disk: SAMPLE.H, SAMPLE.DEF and SAMPLE.RSC. These are 
the files that the RCP created. SAMPLE.H contains all your object and tree names as a series of 
#defines. If you want to refer to the objects by name in your program, you must #include this file in 
your source code. 

The SAMPLE.DEF file contains information the RCP uses for its own purposes, and the SAMPLE.RSC 
file is the tree data for our dialog box. We'll load this data into memory when we run our program. 

So How About Some Details? 

That was a fast course in the use of a resource construction program. You probably have many 
unanswered questions. For example, what do all those attributes do? 

SELECTABLE simply means that the user can select the object. When the object is selected, it will be 
displayed in inverse video. If you set the DEFAULT option when editing an object, the object will be 
selectable with the Return key, as well as with a mouse click. Obviously, only one object at a time can 
be set as a default. 

The EXIT and TOUCHEXIT attributes are similar: they both cause the dialog box to be exited when 
selected. The difference is that, with TOUCHEXIT, the mouse button need not be released to exit the 
dialog box. 

What did you think about the RADIO BUTN option? Radio buttons are handy devices, allowing the 
programmer to set up a series of related buttons, only one of which may be selected at a time. As 
soon as a button is selected, the previously selected button is turned off. They get their name from 
those old car radio tuners with the push buttons to select the channel. An important note: In order 
for radio buttons to operate properly, they must have the same parent object; that is, they all must 
be "on top of" the same object. 
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The CHECKED, SHADOWED, OUTLINED, CROSSED and DISABLED options affect the way the objects 
will be graphically represented on the screen. You can easily see their effect by using your RCP to set 
them for various objects. The options' names describe their effect fairly accurately. 

An EDITABLE object may be modified in some manner by the user. 


Editable Text 

Now, what's the story behind those strange text fields PTMPLT, PVALID, and PTEXT? These three 
strings combine in such a way as to tell GEM which part of the text is editable and what characters 
the user is allowed to input. 

PTMPLT is used as an input mask. Any text entered here will be displayed on the screen and will be 
unchangeable (except underline characters) by the user. PTMPLT also tells GEM where the user can 
edit the text. We indicate this with underline characters. In Step 9 above, the unalterable text is 
"NAME:" and the editable area, where the user will enter his or her name, is represented by the 10 
underlines. 


The PVALID field tells GEM what type of characters we want the input restricted to. Each underline 


character in the PTMPLT fie 


d must have an entry in the PVALID field as fo 


Code 

Characters Allowed 

9 

0 to 9 

A 

A to Z, space 

A 

A to Z, a to z, space 

N 

0 to 9, A to Z, space 

N 

0 to 9, A to Z, a to z, space 

F 

DOS filename characters, plus ? * : 

P 

DOS filename characters, plus \ ? * : 

P 

DOS filename characters, plus \ : 

X 

Any character 


lows: 


In Step 9 we entered 10 lowercase A's in the PVALID field, limiting the user's input to upper- and 
lowercase letters. A logical choice for a person's name. 


Finally, the PTEXT string will be combined with PTMPLT when the latter is printed. Unlike the text in 
PTMPLT, the string stored in PTEXT is editable. This is handy when you want an editable text field 
displayed with a default setting. For example, in Step 9, if we had made the PTEXT string "FRED," 
when the dialog box appeared on the screen, the text cursor would appear to the right of the string 
"FRED." We could then just leave the string as it is, and thus select FRED as our name, or we could 
backspace over it (or use the escape key to clear it) and type in something new. When the user exits 
the dialog box, the new information will be found in PTEXT, replacing what we had stored there 
previously. 


When we set up our editable text objects in Steps 9 and 10, however, we wanted to end up with the 
text cursor to the left of a blank field, ready for the user's input. To do this, we must either enter an 
or a null as the first character of the PTEXT string. To reserve space for any text the user may 
enter, we must fill the rest of the PTEXT string with blanks (actually, any character will work; once 
GEM sees the or null, it'll ignore the rest of the string and go on its merry way). 
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Your First Dialog Box 

When you run this chapter's program (make sure the SAMPLE.RSC file is on the disk!), you'll be 
presented with the dialog box you created with the RCP. Clicking on the OK or CANCEL buttons will 
exit you from the dialog. Clicking on the up or down arrows will cause the value displayed in the 
NUMBERS object to change. Clicking any of the other buttons will cause the name of the object 
selected to be printed at the top of the screen. Notice that, with the radio buttons, only one may be 
selected at a time, while the OPTION 1 and OPTION 2 buttons can be on or off in any combination. 

You may enter your name and age (lie if you want to) in the text fields. Use the arrow keys on your 
keyboard to move between the two fields (or click on them with the mouse), since, due to the OK 
button being set up as a default, pressing Return will exit the dialog box. Try to enter something 
other than upper- or lowercase letters in the name field, or something other than a number in the 
age field. No dice, right? 

When you exit the dialog box, the name and age fields — as well as the final value of the NUMBERS 
object — will be printed to the screen. Notice that whatever is in the PTEXT field is what gets printed. 
If you left the name and age fields blank, you'll see exactly what we put there to start off with, a line 
of spaces preceded by the character. 

After exiting the dialog box, click the left mouse button to return to the desktop. 

Taking It Apart 

Now that we've created our dialog box and played with it a little, it's time to dig into the program a 
bit. 

The first things we should look at are the two structures, object and text_edinfo found near the top 
of the listing. I said earlier that an object, from the program's point of view, was a data structure 
containing the object's description. The data is organized within a C structure as follows: 

typedef struct object { 
int ob next; 
int ob_head; 
int ob_tail; 
unsigned int ob_type; 
unsigned int ob flags; 
unsigned int ob state; 
char *ob_spec; 
int ob x; 
int ob_y; 
int ob w; 
int ob h; 

} OBJECT; 

Here, ob_next is the index of the object's next sibling, ob_head is the index of the object's first child, 
and ob_tail is the index of the object's last child. (Remember that the objects are stored in an array 
of structures. The indices mentioned above are the location of the object within the array.) 

The member ob_type is the object type and will contain one of the following values: 


Object Tvoe 

Value 

Box 

20 

Text 

21 

BoxText 

22 

Image 

23 

ProgDef 

24 


Object Tvoe 

Value 

BoxChar 

27 

String 

28 

FText 

29 

FBoxText 

30 

Icon 

31 
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IBox 

25 

Title 

32 

Button 

26 




The member ob_flags contains the object flags and will be one of the values shown below: 


NONE 

0x0000 

SELECTABLE 

0x0001 

DEFAULT 

0x0002 

EXIT 

0x0004 

EDITABLE 

0x0008 

RBUTTON 

0x0010 

LASTOB 

0x0020 

TOUCHEXIT 

0x0040 

HIDETREE 

0x0080 

INDIRECT 

0x0100 


You should recognize most of these from your work with the RCP. 

The member ob_state holds the current state of the object as follows: 


NORMAL 

0x0000 

SELECTED 

0x0001 

CROSSED 

0x0002 

CHECKED 

0x0004 

DISABLED 

0x0008 

OUTLINED 

0x0010 

SHADOWED 

0x0020 


You've seen most of these before, right? 

The member ob_spec contains object specific information and changes depending on the type of 
object that's being described. The possible values of this field are as below: 


Object Type 

Contents of ob_spec 

Box 

Object's color and thickness 

Text 

Pointer to TEDINFO structure 

BoxText 

Pointer to TEDINFO structure 

Image 

Pointer to BITBLK structure 

IBox 

Border's color and thickness 

Button 

Pointer to text string 

BoxChar 

Object's color and thickness, and the character to display 

String 

Pointer to text string 

FText 

Pointer to TEDINFO structure 

FBoxText 

Pointer to TEDINFO structure 

Icon 

Pointer to ICONBLK structure 

Title 

Pointer to text string 


Notice that the value stored in ob_spec can be a pointer to another structure containing additional 
information on the object. We'll take a look at one of the structures, TEDINFO, shortly. 

Finally, ob_x, ob_y, ob_w, and ob_h contain the object's coordinates, width and height. 
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The Mysterious TEDINFO 

The second structure type in the sample program, text_edinfo, is the declaration for the previously 
mentioned TEDINFO. Whenever our object has an editable text field, we need to store information 
about it in a TEDINFO structure (actually, when using an RCP, we don't have to worry about storing 
information in the structure; it's done for us) as follows: 

typedef struct text_edinfo { 
char *te_ptext; 
char *te_ptmplt; 
char *te_pvalid; 


int 

te font; 

int 

te junkl; 

int 

te just; 

int 

te color; 

int 

te junk2; 

int 

te thickness; 

int 

te txtlen; 

int 

} TEDINFO; 

te tmplen; 


Flere, te_ptext is a pointer to the PTEXT string, te_ptmplt is a pointer to the PTMPLT string, te_pvalid 
is a pointer to the PVALID string, te_font is the text font (3 = system font; 5 = small font), tejust is 
the justification (0 = left; 1 = right; 2 = centered), te_color is the color and pattern type, te_thickness 
is the thickness in pixels of the border (0 = no border; 1 to 128 = thickness inward from the edge; -1 
to -127 = thickness outward from the edge), te_txtlen contains the length of the string pointed to by 
te_ptext, and te_tmplen contains the length of the string pointed to by te_ptmplt. 

As the Fear Sets In 

Relax. In most cases, when using the RCP to put together your dialog box, you won't have to worry 
about the contents of the above structures. But, in case you want to do something more 
sophisticated, you do need to understand where to find information about your dialog box. An 
example of this is the NUMBERS object in the sample dialog. In order to get the up and down arrows 
to change the value shown, we have to be able to get at the displayed strings. This is just one 
example of the creative ways you can use a dialog box. 

Breathing Time 

Your head is probably spinning from all this technical talk. We'll take a break here and give you a 
chance to ponder what you've learned. Spend some time with your resource construction program, 
experimenting with different attribute settings on different objects. As you continue with your career 
as a GEM programmer, the RCP is going to become one of your most valued tools. 
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Program Listing #1 


j*********************************************** I 

/* C-manship, Listing 1 */ 

/* CHAPTER 14 */ 

/* Developed with Megamax C */ 

/***********************************************J 

#include "SAMPLE.H" 

#include <OSBIND.H> 


#define FMD_START 0 
#define FMD_GROW 1 
#define FMD_SHRINK 2 
#define FMD_FINISH 3 
#define R_TREE 0 

#define FINGER 3 

/* The usual required GEM global arrays */ 

int work in[11], 

work_out[57], 

pxyarray[10], 

contrl[12], 

intin [12 8], 

ptsin[128], 

intout[128], 

ptsout[128]; 

/* Global variables */ 
int handle, dum; 


dial 

_x. 

/* 

Dialog x coordinate. 

*/ 

dial 

_y r 

/* 

Dialog y coordinate. 

*/ 

dial 

w. 

/* 

Dilaog width. 

*/ 

dial 

_h, 

/* 

Dialog height. 

*/ 

num. 


/* 

Value of number option. 

*/ 

n x. 


/* 

NUMBERS object x coord. 

*/ 

n_y; 


/* 

NUMBERS object y coord. 

*/ 


char number_str[13] = " 0000 /* NUMBERS string. */ 

char *find str(); /* Function declaration. */ 


/* Structure to hold an object's description. */ 
typedef struct object 
{ 


int 


ob next; 

/* 

Next sibling of object. 

*/ 

int 


ob head; 

/* 

Head of object's children. 

*/ 

int 


ob tail; 

/* 

Tail of object's children. 

*/ 

unsigned 

int 

ob type; 

/* 

Type of object. 

*/ 

unsigned 

int 

ob flags; 

/* 

Flags. 

*/ 

unsigned 

int 

ob state; 

/* 

State of object. 

*/ 

char 


*ob spec; 

/* 

Miscellaneous information. 

*/ 

int 


ob x; 

/* 

x pos of object upper left 

*/ 

int 


ob_y; 

/* 

y pos of object upper left 

*/ 

int 


ob w; 

/* 

Width of object. 

*/ 

int 

} OBJECT; 


ob h; 

/* 

Height of object. 

*/ 


OBJECT *tree_addr; /* Pointer to our object structure. */ 
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/* Structure to hold object text information. */ 
typedef struct text_edinfo 
{ 



char 

*te ptext; 

/* 

Pointer to text. 

*/ 



char 

*te ptmplt; 

/* 

Pointer to template. 

*/ 



char 

*te pvalid; 

/* 

Pointer to validation chars. 

*/ 



int 

te font; 

/* 

Font. 

*/ 



int 

te junkl; 

/* 

Unused. 

*/ 



int 

te just; 

/* 

Justification. 

*/ 



int 

te color; 

/* 

Color information. 

*/ 



int 

te junk2; 

/* 

Unused. 

*/ 



int 

te thickness; 

/* 

Border thickness. 

*/ 



int 

te txtlen; 

/* 

length of text string. 

*/ 



int 

te tmplen; 

/* 

length of template string. 

*/ 


} 

TEDINFO; 






main () 







appl 

_init (); 


/* Initialize application. 

*/ 


open 

vwork (); 


/* Set up workstation. 


*/ 


do dialog(); 


/* Go do the dialog box. 


*/ 


button wait(); 


/* Wait for mouse button. 

*/ 


rsrc 

free () ; 


/* Release resource memory. 

*/ 


v clsvwk (handle); 


/* Close virtual workstation. 

*/ 


appl_ 

exit (); 


/* Back to the desktop. 


*/ 


} 


open vwork () 

{ 

int i; 

/* Get graphics handle, initialize the GEM arrays and open */ 

/* a virtual workstation. */ 

handle = graf^handle (&dum,&dum,&dum,&dum); 
for (i=0; i<10; work in[i++] = 1); 
work in[10] = 2; 

v_opnvwk (work-in, Shandle, work-out); 

} 

do_dialog () 

{ 

int choice; /* Button choice from dialog. */ 

/* Here we load the resource file. If the file is missing, */ 

/* we warn the user with an alert box then terminate the */ 

/* program by skipping the code following the else. */ 

if (! rsrc_load ( "\SAMPLE.RSC" )) 

form^alert (1 ,"[ 1] [SAMPLE.RSC missing!][I'11 do better!]"); 

/* If the resource file loads OK, we get the address of the* / 

/* tree, get the coords for centering the dialog, save the */ 

/* portion of the screen that'll be covered by the dialog, */ 

/* and draw the dialog. The mouse pointer is changed to */ 

/* pointing finger. */ 

else { 

rsrc_gaddr (R TREE, SAMPLE, Stree addr); 

form^center(tree_addr, &dial_x, &dial_y, &dial_w, &dial_h); 
objc_offset (tree_addr, NUMBERS, &n_x, &n_y); 
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} 


form_dial(FMD_START, 0, 0, 10, 10, 

dial_x, dial y, dial^w, dial_h); 
form_dial(FMD_GR0W, 0, 0, 10, 10, 

dial_x, dial y, dial_w, dial_h); 
objc_draw(tree_addr, 0, 2, dialx, dial_y, dial_w, dial_h); 
graf mouse (FINGER,&dum); 


/* Here we allow the user to interact with the dialog then,*/ 


/* 

based 

on the 

chosen button, perform the necessary action 

. */ 

/* 

The form do function is 

repeated until the user 

chooses 

*/ 

/* 

either 

the OK 

button or 

the CANCEL button. 



*/ 

num = 

0; 








do 

{ 











choice = form 

do (tree addr, NAME); 






if 

(choice 

= = 

RADIOl) 

v gtext(handle, 160,20, 

"Radio 

1 

") ; 



if 

(choice 

= = 

RADI02) 

v gtext(handle, 160,20, 

"Radio 

2 

") ; 



if 

(choice 

= = 

RADI03) 

v gtext(handle,160,20, 

"Radio 

3 

") ; 



if 

(choice 

= = 

RADI04) 

v gtext(handle,160,20, 

"Radio 

4 

") ; 



if 

(choice 

= = 

RADI05) 

v gtext(handle,160,20, 

"Radio 

5 

") ; 



if 

(choice 

= = 

RADI06) 

v gtext(handle,160,20, 

"Radio 

6 

") ; 



if 

(choice 

= = 

OPTION1 

) v gtext(handle,160,20 

, "Option 

1") ; 



if 

(choice 

= = 

OPTION2 

) v gtext(handle,160,20 

, "Option 

2 ") ; 



if 

(choice 

= = 

UPARROW) do_up(); 




1 


if 

(choice 

= = 

DWNARROW) do down(); 




/ 

while 

(choice != 

CANCEL && 

choice != OK); 





/* Once the CANCEL or OK buttons have been pressed, we clean */ 
/* up after ourselves by performing the "shrinking box" and */ 
/* then redrawing the screen. */ 


form 

dial(FMD 

SHRINK, 

0 , 0 , 

10, 10, 



dial x. 

dial y. 

dial 

w, dial 

h) ; 

£ 

O 

4-1 

dial(FMD 

FINISH, 

0 , 0 , 

10, 10, 



dial x. 

dial y. 

dial 

w, dial 

h) ; 


print results(tree addr); /* Print user's choices. */ 


do_up () 

{ 

/* First we increment our value and make sure it stays in */ 
/* range. If the value has become larger than 9999, we must */ 
/* also reinitialize display string for the object NUMBERS. */ 
/* We then call our function to update the NUMBERS object. */ 

num += 1; 
if (num > 9999) { 

num = 0; 

strcpy (number_str, " 0000 "); 

} 

edit_object (); 
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do down () 


/* Here we decrement the value and check for its range, 
/* after which we update the NUMBERS object. 


*/ 

*/ 


num -= 1; 

if (num < 0) num = 9999; 
edit_object (); 


edit_object () 

{ 

TEDINFO *ob_tedinfo; 
char temp_str[10]; 

/* Here we edit the string we're using for the text display */ 
/* in the object NUMBERS so that it reflects the new value. */ 

sprintf (temp_str, "%d" ,num); 

strcpy (Snumber^str[8 - strlen (temp_str)],temp^str); 
strcpy (Snumber^str[8], " "); 

/* Then we find the object NUMBERS' TEDINFO and point the */ 

/* te_ptext member to our updated string, after which we */ 

/* redraw the object NUMBERS. */ 

ob tedinfo = (TEDINFO *) tree addr[NUMBERS].ob^spec; 
ob tedinfo -> te_ptext = number str; 

/* For high resolution, change the 16 below to 32. */ 
objc_draw (tree_addr, NUMBERS, 1, n_x, n_y, 96, 16); 


print_results (tree_addr) 

OBJECT tree_addr[]; 

{ 

char *string; 

/* Here we call the function that locates the string, then */ 
/* print the user's input to the screen. */ 

string = find str (NAME, string); 

v gtext (handle, 160, 20, "Your name is "); 

v_gtext (handle, 264, 20, string); 

string = find str (AGE, string); 

v_gtext (handle, 160, 36, "Your age is "); 

v_gtext (handle, 264, 36, string); 

string = find str (NUMBERS, string); 

v_gtext (handle, 160, 52, "Final number value: "); 

v_gtext (handle, 320, 52, &string[4]); 


Port: HYPertext by Lonny Pursell & PDF by DrCoolZic (jig) - VI.0 Oct. 2010 


Page 138/321 


C-MANSHIP COMPLETE - by CLAYTON WALNUT 


char *find_str (object, string) 
int object; 
char *string; 

{ 

TEDINFO *ob_tedinfo; 

/* In this function, we locate the object's TEDINFO */ 

/* structure then set our string pointer to the pointer */ 
/* found in the te_ptext member. */ 

ob_tedinfo = (TEDINFO *) tree_addr[object].ob_spec; 
string = ob^tedinfo -> te_ptext; 
return (string); 

} 

/* Waits for left button to be pressed and released. */ 
button_wait() 

{ 

evnt_button (1,1,1,&dum,&dum,&dum,&dum); 
evnt_button (1,1,0,&dum,&dum,&dum,&dum); 

} 
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CHAPTER 15 - MORE ON DIALOG BOXES 

In chapter 14 we looked at the process of creating a dialog box. In this chapter, we'll tie up some 
loose ends by taking a close look at Chapter 14's sample program. You'll want to refer to that listing 
during the following discussion. 

The Workings 

At the top of the listing, we include the file SAMPLE.H. This file contains the name of the object tree 
that represents our dialog box, as well as the names of all the objects within the tree. Each object is 
given a number. This number is the index used to find the object within the array. (A tree is an array 
of objects, remember?) For those of you who don't have a resource construction program (RCP), 
Listing 1 at the end of this chapter shows what the SAMPLE.H file contains. 

If you do have an RCP, and you put together Chapter 14's dialog box, you may find that your objects 
are numbered differently than those in the example. Don't worry about it. That just means we 
constructed our dialog boxes a little differently. For instance, the example's object numbers don't run 
in perfect order. Some numbers are missing because, in the course of constructing the dialog, I 
removed a couple of objects from the screen without actually deleting them from the tree. Those 
objects were assigned numbers, but since they remain unnamed (and unused), they don't appear in 
the .H file. 

The #defines in Chapter 14's listing assign to logical names the values of various parameters we'll be 
using when handling the dialog. Following that, we have the required GEM array declarations and 
some global variables. 

The character array number_str[] is the string we'll use to change the displayed value of the 
NUMBERS object, in response to one of the arrows being clicked. 

Finally, we get to the two structure types we discussed in Chapter 14, OBJECT and TEDINFO. Of 
course, these are not standard C data types, right? These are our own data types, and we told the 
compiler this by using the typedef keyword in front of the declaration. 

We also declare a pointer to our object structure. This pointer does not, at this time, contain an 
address. We've told the compiler only that when there is an address in *tree_addr, it'll be the 
address of a block of data of the type OBJECT. Also, we don't have an OBJECT or TEDINFO structure in 
memory yet. In our source code, we've only described what they'll look like. If you're confused, take 
a little time to review structures and their declarations. 

And Speaking of the Program... 

Finally, we get to main(). There's not much to discuss here. In keeping with structured style, there's 
only a general "outline" of the program contained in this function. As you can see, our program must 
execute seven main steps. We've left the details of those steps to other functions. The function 
do_dialog() is where the action really begins. 

The first thing we must do to get the dialog box on the screen is load into memory the resource file 
containing all the dialog's information. We do this with the call: 

rsrc_load("filename.rsc"); 

Here, filename.rsc is the name of the resource file that was created by the RCP (note that the 
extension .RSC is a convention you should stick to when naming resource files). This call returns a 0 if 
an error was encountered and a nonzero number if the file loaded okay. 
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Simple, no? In our case, we've used an if statement to prevent the program from continuing if the 
.RSC file is missing. If a 0 is returned, the conditional becomes true, in which case we call up an alert 
box, informing the user that the SAMPLE.RSC file was missing, then skip over the rest of the program 
and exit to the desktop. Once we've got our resource file loaded, we need to find its address. We do 
this with the call: 

rsrc_gaddr(type, index, tree_addr); 

Here, type is the type of data structure loaded, index is the index of the object within the tree (in our 
case, the "object" is a tree), and tree_addr is the address of the information (the tree) loaded from 
the .RSC file. The parameter type should be a value from the following table: 


0 object tree 

1 OBJECT 

2 TEDINFO 

3 ICONBLK 

4 BITBLK 

5 string 

6 image data 

7 obspec (object specification) 

8 te_ptext (pointer to text) 

9 te_ptmplt (pointer text template) 

10 te_pvalid (pointer to text validation string) 

11 ib_pmask (pointer to icon image mask) 

12 ib_pdata (pointer to icon image data) 

13 ib_ptext (pointer to icon text) 

14 ib_pdata (pointer to bit image) 

15 address of a pointer to a free string 

16 address of a pointer to a free image 


The next thing we must do is modify the coordinates of our dialog box so that it'll appear in the 
center of the screen. This is done with the call: 

form_center(tree_addr, &x, &y, &w, &h); 

Here, tree_addr is the address of the object tree (returned from rsrc_gaddr()), and &x, &y, &w, and 
&h are the addresses of the integer variables that will contain the dialog's centered X,Y-coordinates, 
width, and height, respectively. 

Since we'll be doing some work by hand, as it were, on the NUMBERS object in order to update the 
number it displays, we must find its eventual position on the screen. We do this with the call: 

objc_offset (tree_addr, index, &x, &y); 

Here, tree_addr is the address of the tree that contains the object, index is the object's index within 
the tree, and &x and &y are the addresses of the integer variables that will contain the object's 
coordinates returned from the function. 

Now we must reserve space on screen for the dialog. We have to do this so that, when we remove 
the dialog from the screen, GEM will be able to restore the display. The call 
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form_dial(flag,s x, s_y, s_w, s_h, l__x, l_y, 1 w, 1 h) ; 

takes care of this, where flag is the operation you wish the function to perform (in this case, it should 
be 0); s_x, s_y, s_w, and s_h are the X,Y coordinates, width, and height of the smallest rectangle 
(we'll talk about this in a moment); and l_x, l_y, l_w, and l_h are the X,Y coordinates, width, and 
height of the largest rectangle (the actual size of the dialog). The acceptable values for flag are: 


0 

FMD_START 

reserves screen space 

1 

FMD_GROW 

draws expanding box 

2 

FMD_SHRINK 

draws shrinking box 

3 

FMD_FINISH 

releases screen space and does a redraw 


Next, we call form_dial() to perform operation 1, drawing the expanding box. The call looks exactly 
the same as above, except the value of flag is 1. The expanding box is drawn starting with the 
coordinates and size of the smallest rectangle, and ending with the coordinates and size of the 
largest rectangle. Note that the drawing of both the expanding and shrinking boxes is optional. If you 
wish, you can skip over this step and go directly to the call below, which actually draws the dialog. 
One reason you might want to do this is to bring the dialog up faster. 

Finally, we're ready to draw our dialog, with the call: 

objc_draw(tree_addr, object, depth, x, y, w, h); 

Here, tree_addr is the address of the object tree; object is the number of the object to draw; depth is 
how many levels deep the object should be drawn; and x, y, w, and h are the X,Y coordinates, width, 
and height, respectively, of the area of the screen in which the object will actually be drawn, also 
called the "clipping rectangle." 

The clipping rectangle is the portion of the display to which all our screen output is limited. For 
instance, if we print text that'll extend beyond the rectangle's border, the text will be "clipped" to fit; 
anything that would be drawn outside the clipping rectangle will be ignored. Thus we can protect the 
integrity of the rest of the display. 

When we set object to 0 in the above call, we're asking for the first object in the tree to be drawn. 
The first object in a tree is the root -- in our case, the box containing the rest of the objects that make 
up our dialog. To be sure all the objects contained within the dialog are drawn, we must set depth to 
the proper value. If we had set it to 0, only the main box would have been drawn. If we had set it to 
1, only the main box and its children would have been drawn, meaning that our radio button box 
would be missing its buttons and our number box would be missing its arrows. By setting depth to 2 
in the sample program, the main box plus its children and grandchildren (the children of the children) 
are drawn, thus completing our dialog. If you want to be sure you get everything, just set depth to its 
maximum value of 8. 

Now that our dialog is on the screen, how do we find out what the user is doing with it? Simple! 

form_do(tree_addr, object); 

Here, tree_addr is the address of the object tree, and object is the index of an editable text field (0 if 
there are no editable text fields). The value in object tells form_do() the number of the text editable 
field we want to be active at the time of the call. 
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Now that we've made our call to form_do(), GEM will handle the dialog for us, highlighting any 
selectable fields clicked on and letting us enter text into any editable text field. When an exit button 
is clicked, the dialog will be terminated and form_do() will return the number of the button clicked. 
The button number is the only piece of information it returns directly. If we want to see what was 
entered in the strings, we have to hunt. 

Obviously, only EXIT buttons will ever have their values returned from the form_do() call, so if you 
want to know when a button is clicked, make sure, when you design your dialog, that one of the 
button's attributes is EXIT or TOUCHEXIT. 

Actually, that's not entirely true. There is another way to get this information. Each time we click a 
button or fiddle with the dialog in some other way, the object's status is changed and recorded in the 
ob_state member of the OBJECT structure. We'll see how to access the OBJECT structure in a while. 

Because the only time we want to close our sample dialog box is when the OK or CANCEL button is 
clicked, we place the form_do() call within a do/while loop. In the body of the loop, we check to see 
which button was clicked, and perform the necessary action. The loop repeats, continually activating 
and deactivating the dialog, until OK or CANCEL is clicked. Note that the call to form_do() doesn't 
redraw the dialog; it only notifies GEM to accept more input from the form. 

When the user has finished with the dialog, we must remove it from the screen. We do this by 
performing two more form_dial() calls: one to display the shrinking box (flag=2), and one to restore 
the screen (flag=3). 

Finding the Data 

In our sample dialog, when a button is clicked, all the program does is print the object's name. But 
when the user clicks on one of the arrows, we have to find a way to change the value shown in the 
NUMBERS object. This is where things get a little sticky. Your knowledge of pointers and structures is 
about to be pushed to the limit. 

Think back to when you created the dialog. The object NUMBERS is a BOXTEXT object — a graphic box 
containing a string. It's this string that displays the value of num (the variable that holds the most 
current value selected by the arrows). When the user clicks on one of the arrows, we must increment 
or decrement num, then modify the string displayed in the object NUMBERS. In our program, the 
string we'll be modifying is number_str. But, until we change the pointer contained in te_ptext, the 
dialog doesn't know anything about our string. It's perfectly happy with the string we gave it at the 
beginning. 

So... 

In Chapter 14 we discussed the OBJECT and TEDINFO structures. I told you that the OBJECT structure 
contained a field called ob_spec that holds object-specific information. When the object being 
described is of type BOXTEXT, ob_spec holds a pointer to a TEDINFO structure. (See the ob_spec 
chart in Chapter 14.) And guess where we'll find that pointer we want to fiddle with? 

Yep. 

So, let's say the user clicks on the up arrow. At that point, program execution jumps to the function 
do_up(), where num is incremented. The if statement makes sure the displayed value doesn't exceed 
9999. If num gets too big, we reset it to 0 and copy a new string reflecting this change into 
number_str. We then call edit_object(), the function that'll force NUMBERS to display the string we 
want it to, instead of its own. 

Dealing with TEDINFO 

This is where things get tricky, so make sure your thinking caps are in working order. 
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The first thing we do in edit_object() is to declare a pointer, *ob_tedinfo, to a TEDINFO structure. 
Also, at the beginning of this function, we declare a 10-character string to temporarily hold the text 
we'll be setting up. 

The first three lines of actual code in edit_object() convert the value in num to string form, then place 
this new string into number_str. We have to do all that fancy string handling to make sure the 
numbers are placed in the proper position, retaining any leading zeros, as well as the four spaces 
before and after the number. 

That was the easy part. Now we have to find the pointer that points to the string contained in the 
NUMBERS object, so that we can change it to point to our own string. Remember that our tree, 
which is now pointed to by tree_addr, is an array of structures, each structure describing one of the 
objects within the tree. Just like any other array, it lets us get to a particular element by using an 
index. The object whose structure we wish to locate is NUMBERS, and, thanks to our handy RCP, 
NUMBERS has been #defined in the SAMPLE.H header file to the value of the index we need. 

The ob_spec member of the structure that describes NUMBERS contains a pointer to the TEDINFO 
structure that holds the pointer to our string. Yikes! I feel an illustration coming on. Figure 1 ought to 
help you sort this tangle out. 

Got it? 

So the address of NUMBERS'S TEDINFO structure is: 

tree_addr[NUMBERS].ob spec 


This is the address we store in ob_tedinfo (after casting it into a pointer to TEDINFO). 


Now that ob_tedinfo points to NUMBERS's TEDINFO structure, it's a simple matter to get at the 
address of the string. 


OBJECT 

TREE 



OBJECT 


TEDINFO 

OBJECT'S 

STRUCTURE 


STRUCTURE 

STRING 

OB_NEXT 



TE_PTEXT 

->| 0000 

OB_HERD 



TE_PTMPLT 


OB_TRIL 



TE_PURLID 


OB_TVPE 



TE_FONT 


OB_FLRGS 



TE_JUNK1 


OB_STRTE 



TE_JUST 


OB_SPEC 



TE_COLOR 


OB_X 


TE_JUNK2 


OB_V 


TE_THICK 


OB_W 


TE_TXTLEN 


OB_H 


TE_TMPLEN 



FIGURE 1 - Locating an object's text 

The address is contained in the element te_ptext, so the statement below changes this pointer to 
point to our own string. 


ob_tedinfo->te_ptext = number_str; 


Once we have the string we created included as part of NUMBERS, all we have to do is redraw the 
object with the call: 
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objc_draw(tree_addr, NUMBERS, depth, x, y, w, h); 

Here, the parameters are the same as those described above. The height value of 16 used in the 
program is for medium resolution. To get the dialog to work properly in high resolution, since the 
monochrome screen has twice the resolution, you must change this value to 32. To make your dialog 
work automatically in any resolution, you can get the values for w and h from the ob_w and ob_h 
members of the object's OBJECT structure. 

Releasing Resource Memory 

When we load a resource file, we are obviously using up some of our system's memory. The memory 
that has been reserved for our resource file should be returned to the system before we exit the 
program or before we try to load another resource file. We release the memory occupied by a 
resource file with this function call: 

rsrc^free(); 

If you look at our sample program from Chapter 14, in main(), you'll see that we are releasing the 
resource before we close the virtual workstation and exit the program. 

Knowing Who Your Friends Are 

In Chapter 14 I said that the resource construction program was going to be one of your most valued 
tools. It saves the programmer an immense amount of time, by generating most of the data needed 
to bring a dialog box (or any other object tree) up on the screen. 

But you don't have to use an RCP to program a dialog. You can do it directly from C -- if you're the 
type of person who likes outrageously meticulous tasks. 

Listing 2 at the end of this chapter will give you some idea of what I'm talking about. This listing was 
created by the Resource Construction Set that comes with the Atari Developer's Kit. Compare what 
you see with all you've learned about dialog boxes, especially with respect to OBJECT and TEDINFO 
structures. You should be able to identify many of the components of our dialog. 

For instance, right at the top of the listing, immediately after the #define statements, are all the 
strings we need, including templates and string validation fields. Below that is the data for the 
ANALOG "A" icons. Each icon consists of the actual data plus a mask, so we end up with four arrays, 
two for each icon. A little farther down, you can see the arrays of TEDINFO and OBJECT structures. 
Each line of these arrays makes up the data for one of the structures. Compare what you see with 
the structures illustrated in Figure 1. 

Listing 2 appears here in exactly the same form as it was output from the RCS. There's still some 
information that needs to be filled in by the programmer. For instance, look at the first line of the 
TEDINFO array. The "11L" is the first TEDINFO's string pointer (te_ptext). Right now, this value is just 
an offset from the beginning of the strings defined at the top of the listing. If you start at zero and 

count down to eleven, you'll find that this te_ptext is associated with the string _" (each 

represents a space character), which is the blank field for our NAME object. 

The array of objects that make up our dialog is found right below the TEDINFOs. Just like the 
TEDINFO array, each line here consists of the data for each object's structure. Isn't this fun? How'd 
you like to code all this stuff by hand? 
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Closing Up Shop 

This finishes up our introduction to dialog boxes. By now, you should have a good idea of how 
versatile they can be. With a little creativity, you could write an entire program that used nothing but 
dialog boxes for all its input and output. Don't be afraid to experiment. Get as outrageous as you like! 
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Program Listing #1 

#define SAMPLE 0 
#define OK 4 
#define CANCEL 3 
#define RADI02 6 
#define RADI01 8 
#define RADI04 7 
#define RADI03 9 
#define RADI05 10 
#define RADI06 11 
#define NAME 17 
#define AGE 18 
#define OPTION2 14 
#define OPTION1 13 
#define NUMBERS 19 
#define DWNARROW 16 
#define UPARROW 15 


Program Listing #2 

#define TOOBJ 0 
#define FREEBB 0 
#define FREEIMG 4 
#define FREESTR 29 

BYTE *rs_strings[] = { 

II fl 

r 

u ii 

t 

"CANCEL", 

"OK", 

" #2 " , 

" #4 " , 

"# 1 ", 

"#3" , 

"#5" , 

" # 6 " , 

"RADIO BUTTONS", 

"@ 

"NAME: _ 

"aaaaaaaaaa" , 

"@ ", 

"AGE: _ ", 

"99", 

"OPTION 1", 
"OPTION 2", 

" 0000 


/* this contains 'SPACE CONTROL-B SPACE' 


+ ", /* this contains 'SPACE CONTROL-A SPACE' 


"THIS IS A SAMPLE DIALOG BOX" 

} ; 
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WORD IMAGO[] 

= { 



OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF 


} ; 

WORD IMAGI[] = { 

0x7, OxFFFF, OxFFFC, OxF, 
OxFFFF, OxFFFE, OxlF, OxFFFF, 
OxFFFE, 0x3F, OxFFFF, OxFFFE, 
0x7F, OxFFFF, OxFFFE, OxFF, 
OxFFFF, OxFFFE, OxFF, OxFOOO, 
OxFFE, OxFF, OxFOOO, OxFFE, 
OxFF, OxFOOO, OxFFE, OxFF, 
OxFFFF, 0x8FFE, OxFF, OxFFFF, 
OxCFFE, OxFF, OxFFFF, OxCFFE, 
OxFF, OxFFFF, 0x8FFE, OxFF, 
OxFOOO, OxFIE, OxFF, 0xF800, 
OxEOE, OxFF, OxFCOO, OxEOE, 
OxFF, OxFEOO, OxFIE, OxFF, 
OxFFOO, OxFFE, OxFF, OxFFOO, 
OxFFE, 0x0, 0x0, 0x0, 


0x0, 0x0 

, 0x0, 

0x0, 


0x0, 0x0 

, 0x0, 

0x0, 


0x0, 0x0 

} ; 

WORD IMAG2[] = 
OxFFFF, 

, 0x0, 

0x0 


= ( 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF, 

OxFFFF 


} ; 
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WORD IMAG3[] = { 

0x7, OxFFFF, OxFFFC, OxF, 
OxFFFF, OxFFFE, OxlF, OxFFFF, 
OxFFFE, 0x3F, OxFFFF, OxFFFE, 
0x7F, OxFFFF, OxFFFE, OxFF, 
OxFFFF, OxFFFE, OxFF, OxFOOO, 
OxFFE, OxFF, OxFOOO, OxFFE, 
OxFF, OxFOOO, OxFFE, OxFF, 
OxFFFF, 0x8FFE, OxFF, OxFFFF, 
OxCFFE, OxFF, OxFFFF, OxCFFE, 
OxFF, OxFFFF, 0x8FFE, OxFF, 
OxFOOO, OxFIE, OxFF, 0xF800, 
OxEOE, OxFF, OxFCOO, OxEOE, 
OxFF, OxFEOO, OxFIE, OxFF, 
OxFFOO, OxFFE, OxFF, OxFFOO, 
OxFFE, 0x0, 0x0, 0x0, 


0x0, 

0x0, 

0x0, 

0x0, 

0x0, 

0x0, 

0x0, 

0x0, 

0x0, 

0x0, 

0x0, 

0x0 

}; 




LONG rs frstrj] 

= {0} 

r 


BITBLK rs_bitblk[] = {0}; 
LONG rs_frimg[] = {0}; 
ICONBLK rs iconblk[] = { 


OL, 

1L, OL, 4096, 

O 

O 

0, 

CN 

CO 

o 

4,21 

CM 

O 

2L, 

} ; 

3L, 1L, 4096, 

0,0, 

0, 

0,48,24, 

4,21 

,40,2 

TEDINFO rs 

tedinf o [ ] 

_ 

{ 





11L, 

12L, 13L, 

3, 

6, 

0, 

0x1180, 

0x0, 

255, 11,17 

14L, 

15L, 16L, 

3, 

6, 

0, 

0x1180, 

0x0, 

255, 3,8, 

19L, 

20L, 21L, 

3, 

6, 

2, 

0x1180, 

0x0, 

255, 13,1, 

22L, 

23L, 24L, 

3, 

6, 

0, 

0x1180, 

0x0, 

255, 4,1, 

25L, 

26L, 27L, 

3, 

6, 

2, 

0x1180, 

0x0, 

255, 4,1 


} ; 
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OBJECT 


' rs 

obj ect[ 

:i = { 




-1, 

1, 

20, 

G BOX, NONE, OUTLINED, 0x21140L, 

0,0 

\ — i 

CO 

LO 

2, 

-1, 

-1, 

G ICON, NONE, NORMAL, OxOL, 4,1, 

6,3 

r 

3, 

-1, 

-1, 

G ICON, NONE, NORMAL, OxlL, 47,1, 

6, 

3, 

4, 

-1, 

-1, 

G BUTTON, 

0x41, NORMAL, 0x2L, 48, 

11, 

8,2, 

5, 

-1, 

-1, 

G BUTTON, 

0x43, NORMAL, 0x3L, 48, 

8, 

8,2, 

13, 

6, 

12, 

G BOX, NONE, SHADOWED, OxFFllOOL, 

2, 

4, 24,9, 

7, 

-1, 

-1, 

G BUTTON, 

0x51, NORMAL, 0x4L, 13, 

3, 

8,1, 

8, 

-1, 

-1, 

G BUTTON, 

0x51, NORMAL, 0x5L, 13, 

5, 

8,1, 

9, 

-1, 

-1, 

G BUTTON, 

0x51, NORMAL, 0x6L, 3,3 

, 8 

,1, 

10, 

-1, 

-1, 

G BUTTON, 

0x51, NORMAL, 0x7L, 3, 

5, 

8,1, 

\ — 1 
\ — 1 

-1, 

-1, 

G BUTTON, 

0x51, NORMAL, 0x8L, 3, 

7, 

8,1, 

12, 

-1, 

-1, 

G BUTTON, 

0x51, NORMAL, 0x9L, 13 

,7, 

8,1, 

5, 

-1, 

-1, 

G STRING, 

NONE, NORMAL, OxAL, 5,1 

, 13,1, 

14, 

-1, 

-1, 

G FTEXT, 

EDITABLE, NORMAL, OxOL, 

28 

,4, 16,1 

15, 

-1, 

-1, 

G FTEXT, 

EDITABLE, NORMAL, OxlL, 

28 

,6, 7,1, 

16, 

-1, 

-1, 

G BUTTON, 

0x41, SHADOWED, OxllL, 

27 

,8, 9,2, 

l> 

\ — 1 

-1, 

-1, 

G BUTTON, 

0x41, SHADOWED, 0xl2L, 

37 

, 8, 9,2, 

20, 

18, 

19, 

G BOXTEXT 

, NONE, SHADOWED, 0x2L, 

31 

,11, 12, 

19, 

-1, 

-1, 

G BOXTEXT 

, TOUCHEXIT, NORMAL, 0x3L, 

0,0, 3, 

l> 

\ — 1 

-1, 

-1, 

G BOXTEXT 

, TOUCHEXIT, NORMAL, 0x4L, 

9,0, 3, 

0, 

-1, 

-1, 

G STRING, 

LASTOB, NORMAL, OxlCL, 

15, 

1, 29,1 


LONG rs trindex[] = {OL}; 


struct foobar { 
WORDdummy; 
WORD*image; 

} rs_imdope[] = { 

0, & IMAGO [0], 
0, &IMAG1[0], 
0, &IMAG2 [ 0], 
0, &IMAG3[0] 

} ; 


#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 


NUM^STRINGS 29 
NUM^FRSTR 0 
NUM^IMAGES 4 
NUM_BB 0 
NUM^FRIMG 0 
NUM^IB 2 
NUM_TI 5 
NUMjDBS 21 
NUM TREE 1 


BYTE pname[] = "SAMPLE.RSC" ; 
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CHAPTER 16 - MENU BARS 

Now that we know everything there is to know about dialog boxes (well, maybe not everything), it's 
time to move on to menu bars. Second only to windows, menu bars are one of the most 
characteristic features of GEM. Because they're an excellent way to organize the large number of 
options complex programs offer the user, virtually every GEM program uses them. 

You'll be surprised to hear that menu bars are actually much easier to program than dialog boxes. In 
fact, they're so easy that we can cover them in a single chapter, rather than the two it took for dialog 
boxes. 

Another RCP Tutorial 

Before we can go any further, you're going to have to load up your Resource Construction Program 
and create the object tree for the sample menu bar. The following steps will guide you through the 
entire construction process. It's not as detailed as the instructions I gave in the last RCP tutorial; you 
should be familiar with using the RCP by now. I can't hold your hands forever — they get too sweaty. 

So get to work, and I'll meet you after Step 24. 

Steppin' Through the Menu Bar 

Step 1: Click on the "New" selection from the File menu. A window titled NONAME will be opened. 
Just as when we constructed our dialog box a couple of chapters ago, this window is where 
we'll work on our menu bar. 

Step 2: Drag the menu icon from the left of the screen into the newly created window. A dialog box 
will appear, prompting you for the name of the menu tree. Press Return to select the 
default name of TREEOO. The menu tree icon will appear in the work window. 

Step 3: Double-click the menu tree icon. The beginnings of your menu bar will appear in the work 
window. 

Step 4: Give the Desk menu selection (on your menu bar, not the RCP's) a single click, and then 
press Control-N. The dialog box for naming objects will appear. Name this object "DESK." 

Step 5: Repeat Step 4 for the File menu selection, naming this object "FILE." 

Step 6: Drag the word TITLE from the parts list and place it to the right of the File title. Double-click 
this new menu bar title. A dialog box will appear. Change the text to two spaces followed by 
the word "Options," followed by another two spaces. 

Step 7: Place the mouse pointer on the lower right-hand corner of the title's shaded area and, 

holding down the left button, expand the shading to the right, centering the title within it. 
Click once on the options title to select it. Then press Control-N and name the object 
"OPTIONS." 

Step 8: Set up another menu title in the same way, entering the text as two spaces followed by the 
word "Selections," followed by two more spaces. Name the object "SELECTS." 

Step 9: Give the Desk menu selection a single click. Then double-click the "Your message here" 
entry. Change the text to two spaces followed by "C-manship info..." and press Return. 

Press Control-N, and name the entry "INFO." 

Step 10: Give the File menu selection a single click. Then place the mouse pointer on the lower-right 
corner of the QUIT object. Holding down the left button, reduce the length of the object by 
dragging the corner to the left. You have to do this in order to uncover the menu box 
beneath. 
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Step 11: Place the mouse pointer on the lower-left corner of the menu box and, holding down the 
left mouse button, drag the box downward, enlarging it so that it can accommodate three 
more entries. 

Step 12: Place the mouse pointer on the QUIT object and, holding the left button down, move the 
object to the bottom-most position of the menu box. 

Step 13: Drag the word "ENTRY" from the parts list and place it in the top position of the File menu 
box, making sure you place it as far to the left as it'll go. Double-click it, and change the text 
to two spaces followed by "Load...", followed by two more spaces. Name the object 
"LOAD." 

Step 14: Create another menu entry below LOAD. The text should be two spaces followed by 
"Save...", followed by two more spaces. Name this object "SAVE." 

Step 15: Drag the-icon from the parts list and place it below the SAVE entry, all the way to 

the left. Then move the QUIT object just below it and name it "QUIT." 

Step 16: Reduce the menu box to its smallest size using the same method as when you enlarged it 

(Step 11). Add enough dashes to the-object (by double-clicking on it and changing 

the text) to extend it to the right-hand margin of the menu box. 

Step 17: Single-click the Options menu title, and enlarge the menu box to accommodate three 
entries. 

Step 18: Drag an ENTRY icon to the top of the Options menu box. Set the text to two spaces 

followed by "Option 1," followed by two more spaces. Before closing the dialog, set the 
CHECKED option in the attributes list. Name the object "OPTION1." 

Step 19: Create two more entries in the options menu box, named "OPTION2" and "OPTION3," and 
place them in order below OPTION1. The spacing of the text will be the same as in Step 18. 
Do not set the CHECKED attribute for these two objects. Reduce the Options menu box to 
its smallest possible size. 

Step 20: Single-click the Selections title. Then stretch the menu box to accommodate five entries. 

Step 21: Create an entry in the Selections menu named "ONOFF," and enter into the text field five 
spaces followed by "On" followed by five more spaces. 

Step 22: Drag the-icon to a position below the ONOFF entry. Add two dashes to the already 

existing ten in the text field. 

Step 23: Create three entries below the dashed line. The entries should be named "SELECT1," 

"SELECT2," and "SELECT3." Their text fields should contain two spaces followed by "Select 
n" (where n is the entry's number as indicated by the names above), followed by two 
additional spaces. 

Step 24: Reduce the Selections menu box to its smallest possible size. 

The Program 

Now that you've got your version of the menu bar saved in a resource file, compile Listing 1, found at 
the end of this chapter. When you run the program, the menu bar you created will come up on the 
screen (make sure you have the MENU.RSC file on the same disk as your .PRG file). First pull down 
the Desk menu and click on "C-manship info..." An alert box should appear, giving you a little 
information about C-manship (very little, actually). 

There are two GEM menu conventions used here. First, you should always place the "Info" selection 
of your menu bar as the first choice of the Desk menu. Second, any menu entry that will lead to a 
dialog box of some sort should be followed by ellipsis dots (three periods). 
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If you had any accessories on your program disk when you booted it, they should also be available on 
the desk menu. Go ahead; check them out. 

Now pull down the File menu. There are a few more conventions to take note of here. If you plan to 
allow the loading and saving of files from your application, this is where the appropriate menu 
entries should go. Ditto for Quit commands. When you follow these conventions, users will always 
know where in a menu bar to find these basic functions. Any other disk handling activities, such as 
Delete, should also be located here. 

In our sample menu, clicking on Load or Save just prints a message to the screen. Quit, of course, 
returns you to the desktop. Note that the Load and Save entries are followed by ellipsis dots, even 
though, in this case, they don't lead to a dialog box. Why? Well, when you use them in a real 
program, they'll almost certainly lead to a file selector box, right? 

Now we get to the Options menu. The three entries found here may be turned on and off by clicking 
them with the mouse. Any options that are active will have a checkmark next to them. You can have 
as many of them active as you wish (especially considering, due to the stripped-down nature of the 
demo program, they don't really do anything, anyway!) 

Moving right along, we get to the Selections menu. The top entry will toggle between the words ON 
and OFF each time it's clicked. When the entry is "on," the selections below will be selectable, and 
will print a message to the screen when they're clicked. 

When the entry is "off," the other selections will be "grayed out." This means they have been 
disabled. No amount of clicking on a disabled menu entry will give you the slightest response, except 
removing the drop-down menu from the screen. This is why we can get away with those dashes 
separating different sections of the menus. Since they're disabled, the user can't do anything with 
them. 

Menu Bars in Your Program 

Now that you've had a chance to fiddle with your creation, let's see how the program works. All the 
action is in the function do_menu(), so let's skip over the other stuff. You should be familiar enough 
by now with how to initialize GEM. 

First, we declare menu_adr, a longword that'll contain the address of our menu tree. The actual code 
begins with the initialization of some flags we'll use to keep track of the status of the various menu 
options. Then we set the mouse pointer to the arrow form. 

Next, we load the resource file from disk, using rsrc_load(), which I described in Chapter 15. If the 
MENU.RSC file is missing, we warn the user with an alert box, then return to the desktop. 

If the resource file loads okay, we find the address of the menu tree, using the rsrc_gaddr() call -- 
which we also discussed in Chapter 15 -- storing the returned address in menu_adr. 

To display our menu bar, we call: 

menu bar(menu adr, flag); 

Here, menu_adr is the address of the menu's object tree and flag is a Boolean value indicating 
whether the menu should be displayed (a nonzero value) or removed (a zero value). 

A Nifty Message System 

Up until now we've been able to get our user's input with either specific calls to the mouse or 
keyboard, or by using dialog and alert boxes. We've now gotten to the point in our GEM 
programming careers where the simple calls just won't do the job. What if we want to be alerted to 
more than one form of input? What if we want to know about the mouse and the keyboard at the 
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same time? More to the point for this chapter, how do we know what the user is doing with the 
menu bar? 

GEM supplies us with a single function call that will monitor the entire system for us and tell us 
everything we need to know about the user's actions. Are you ready? Take a deep breath, because 
you're going to need it. The call (as shown in the Megamax manual) is: 


evnt multi(mmflags, mbclicks, mbmask, mbstate, mmlflags, mmlx, mmly, 
mmlwidth, mmlheight, mm2flags, mm2x, mm2y, mm2width, 
mm2height, mmgpbuff, mtlocount, mthicount, mmox, mmoy, 
mmobutton, mmokstate, mkreturn, mbreturn); 


Sheesh! I warned you! But before you burn your compilers and open your wrists, you should know 
that, at this point, there are only a few of the above parameters we're interested in. We'll be 
discussing this function a lot in upcoming chapters. We'll cover the parts we need bit by bit. For now, 
let's just say that you don't need to use all the parameters. We can send Os for any outgoing 
parameters we're not interested in, and supply dummy locations for any unneeded information 
being sent back. In our menu bar program, the evnt_multi() call looks like this: 

evnt_multi(MU_MESAG, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 

msg_buf, 0, 0, &dum, &dum, &dum, &dum, &dum, &dum); 

MIMVIESAG is the event we want to watch for (in this case, a message event), and msg_buf is the 
address of a 16-byte message buffer where our messages will be stored. 

There are six event types we can wait for. To wait for more than one type of event at a time, we just 
OR the appropriate flags together. For example, to wait for a message event, a keyboard event, and a 
mouse button event, our first parameter in the evnt_multi() call would be: 

MU_MESAG | MU_KEYBD | MU_BUTTON 

Here, MU_MESAG has been defined as 0x0010, MU_KEYBD has been defined as 0x0001, and 
MU_BUTTON has been defined as 0x0002. This sets the proper bits, as shown in the following table. 


Set bit # 

Event 

0 

Keyboard 

1 

Mouse button 

2 

Mouse event 1 

3 

Mouse event 2 

4 

Message event 

5 

Timer event 


Note that, even though we're not using the call this way in the sample program, since we're only 
waiting for one type of message, evnt_multi() returns a word value that will have bits set based on 
the events that occurred. These bits follow the same format as the table above. It's possible to have 
more than one event detected by a single call to evnt_multi(), so it's up to the programmer to check 
each bit in the returned integer, in order not to miss events. If you're checking for more than one 
event, your evnt_multi() call should look something like this: 
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event = evnt multi(...); 

Here, event is the integer that will contain bits set based on the events detected by the call. Of 
course, the in the parentheses will be replaced by that horrendous parameter list. When we 
make the evnt_multi() call, everything comes to a stop until the event we're waiting for occurs. If the 
event is a message event, information about the message is stored in the message buffer. In our 
program, we've set up the array msg_buf[] to handle this duty. The type of message will be returned 
into msg_buf[0]. There are thirteen possible messages, but the only one we're interested in right 
now is the menu selected message, which has a value of 10. When the user makes a selection from 
the menu, therefore, msg_buf[0] will contain 10. 

Since this is the only type of message we're waiting for, we don't have to check msg_buf[0]. We can 
just assume that we've received the message we expected. 

If this discussion is getting confusing, you might not be sure of the differences between an event and 
a message. They are not the same thing. A message is received only when a message event — one of 
six different events -- is detected. 

Enough of this Event Junk 

Now that we have an idea of how evnt_multi() works, the program's workings are fairly simple. The 
object number of the chosen menu title is stored in msg_buf[3], and the object number of the 
chosen menu entry is stored in msg_buf[4j. Once we have that information, we set up nested switch 
statements to perform the appropriate actions. 

The outer switch tests msg_buf[3] to see which menu title was selected. In the sample listing, you'll 
see that there's a case for each menu title. Within each menu title's case is a switch to test 
msg_buf[4], the object number of the selected menu entry. This is the best way to handle menu 
messages -- the code looks very much like the menu bar it represents, and so is clear and easy to 
follow. 

Now, let's look at this code in a little more detail, starting with DESK. Since we have only one action 
we have to take care of, we really didn't need the inner switch statement; we could have used an if, 
but I wanted to keep that "menu-looking" structure I mentioned before. Here, if the user clicks on 
the "C-MANSHIP INFO..." entry, we just call up an alert box. Simple. We don't have to handle any 
desk accessories the user might run; GEM does that for us — almost. I say almost, because, if a desk 
accessory is called up, it's up to your program to redraw the screen after the accessory has done its 
thing. Since we don't have anything special happening in the sample program, we can ignore this 
bothersome detail. 

The File menu selections do nothing fancy, just print a message to the screen. But look at the case 
statements. Where's Quit? Wasn't that part of the File menu? Yes, indeed. And you'll find it at the 
very bottom of the sample listing. We're using it to break out of the do/while loop. 

The Options selections must handle the check marks that indicate active options. We use the call: 

menu icheck(menu adr, OBJECT, flag); 

Here, menu_adr is the address of the menu's object tree, OBJECT is the number of the entry you wish 
to check or uncheck, and flag is a Boolean value that indicates whether a check mark should be 
drawn (a nonzero value) or removed (a zero value). 

In our menu_icheck() calls, we're taking care of not only the check marks, but also the flags — 
reversing them within the function call with the statement below: 
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opl=!opl 

How does this work? First, the flag is changed to its opposite state with the NOT operation. Then this 
new value is passed as the flag to the function. This is one of the advantages of C, being able to nest 
assignments and expressions. 

In the Selects menu section, if the ONOFF entry is selected, we must first change the text in ONOFF, 
then either enable or disable the other selections. To change the text of the entry, we use the call: 

menu text(menu adr, OBJECT, s); 

Here, menu_adr is the address of the menu bar's object tree, OBJECT is the entry's object number, 
and s is the address of the string you wish placed in the object. You should make sure that you've left 
room in the menu for the largest string you'll be using. Otherwise, you'll mess up the desktop. Also, 
you must make sure that the string is statically allocated; that is, it's global, not declared within a 
function. You never know when the user is going to activate that particular menu selection, and if 
your string isn't available globally, it may not be there when the menu is displayed. What a surprise 
that'll be. 

Finally, we use the flag on to determine if we should enable or disable the rest of the menu entries. 
To perform this function, we use the call: 

menu ienable(menu adr, OBJECT, flag); 

Here, menu_adr is (you guessed it) the address of the menu tree, OBJECT is the object of the entry 
you wish to modify, and flag is a Boolean value that indicates whether the entry is to be enabled (a 
nonzero value) or disabled (a zero value). In the sample program, we're using the same trick we used 
with menu_icheck() to handle the flag, but since we have three calls to menu_ienable(), we reverse 
the flag only in the first one. 

When the user moves the mouse pointer over a menu selection, the title of that selection is 
highlighted, and the associated menu drops down. Once the user has clicked on an entry, the drop¬ 
down menu is removed, but the title remains highlighted. The highlighting reminds the user which 
menu selection is currently being processed. By leaving the title highlighted even after the user has 
made his selection, we can perform the actions required by the user's choice, then turn the 
highlighting off when we're ready. We turn off the highlighting with the call: 

menu tnormal(menu adr, title, flag); 

Here, menu_adr is the address of the menu tree, title is the object number of the menu title we wish 
to unhighlight, and flag is a Boolean value that indicates if the title is to be highlighted (a nonzero 
value) or unhighlighted (a zero value). The value for title will be the one found in msg_buf[3]. 

And, last but not least, once we're through with the menu bar, we must remove it from memory. We 
just use the menu_bar() call discussed previously to do this. Just change the flag to false. 

Another Lesson Learned 

Your repertoire of GEM programming tricks is building fast. It won't be long before you'll be ready to 
put together some professional looking software. Learning to handle menu bars is an important step 
in that direction. Without them, you can't really consider yourself a GEM programmer. 

Of course, there's still a lot more we have to cover before we can consider GEM a challenge met. But 
we're getting there. 
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Program Listing #1 

/***********************************************/ 

/* C-manship, Listing 1 */ 

/* CHAPTER 16 */ 

/* Developed with Megamax C */ 

/***********************************************/ 

#include "MENU.H" 

#define MU_MESAG 0x0010 

#define ARROW 0 

#define R_TREE 0 

#define TRUE 1 

#define FALSE 0 

/* The usual required GEM global arrays */ 
int work in[11], 
work-out[57] , 
pxyarray[10], 
contrl[12], 
intin[128], 
ptsin[128], 
intout[128], 
ptsout[128]; 

/* Global variables */ 
int handle, dum; 

int msg_buf[8], opl, op2, op3, on; 

char *alrt = "[1][C-manship, Chapter 16|by Clayton \ 

Walnum][Okay]"; 

char *on_str = " On "; 

char *off_str = " Off "; 

main () 

{ 

appl_init (); 
open vwork () ; 
do_menu(); 
v_clsvwk (handle); 
appl_exit (); 

} 

open^vwork () 

{ 

int i; 

/* Get graphics handle, initialize the GEM arrays and open */ 
/* a virtual workstation. */ 

handle = graf handle ( &dum, &dum, &dum, &dum); 
for ( i=0; i<10; work in[i++] = 1 ); 
work in[10] = 2; 

v_opnvwk ( work in, Shandle, work-out ); 

} 


/* Initialize application. */ 
/* Set up workstation. */ 
/* Go do the MENU. */ 
/* Close virtual workstation. */ 
/* Back to the desktop. */ 


do menu () 
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{ 

long menu adr; /* Address of the tree containing our menu. */ 

/* First, we initialize our option flags, so we can keep */ 

/* track of which ones are active. Also, we change the */ 

/* mouse pointer to an arrow. */ 

op1 — TRUE; 

op2 = FALSE; 

op3 = FALSE; 

on = TRUE; 

graf^mouse ( ARROW, &dum ); 

/* Here we load the resource file. If the file is missing,*/ 

/* we warn the user with an alert box then terminate the */ 
/* program by skipping the code following the ELSE. */ 

if ( ! rsrc_load ( "\MENU.RSC" ) ) 

form alert ( 1, "[1][MENU.RSC missing!][Okay]" ); 

/* If the resource file loads OK, we get the address of the*/ 

/* tree, then handle menu messages from evnt multi(). */ 

else { 

rsrc_gaddr ( R TREE, TREEOO, Smenu adr ); 
menu bar ( menu adr, TRUE ); 
do { 

evnt_multi ( MU_MESAG,0,0,0,0,0,0,0,0,0,0,0,0,0,msg_buf, 
0,0,&dum,&dum,&dum,&dum,&dum,&dum ); 

switch ( msg_buf[3] ) { 

case DESK: 

switch ( msg_buf[4] ) { 

case INFO: 

form_alert ( 1, alrt ); 
break; 

} 

case FILE: 

switch ( msg_buf[4] ) { 

case LOAD: 

v_gtext ( handle, 20, 120, "Load file " ); 
break; 
case SAVE: 

v_gtext ( handle, 20, 120, "Save file " ); 
break; 

} 

case OPTIONS: 

switch ( msg_buf[4] ) { 

case OPTION1: 

menu icheck ( menu adr, OPTION1, opl=!opl ); 
break; 

case OPTION2: 

menu icheck ( menu adr, OPTION2, op2=!op2 ); 
break; 

case OPTION3: 

menu icheck ( menu adr, OPTION3, op3=!op3 ); 
break; 

} 
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case SELECTS: 

switch ( msg_buf[4] ) { 

case ONOFF: 
if ( on ) 


menu text 

( menu 

adr. 

ONOFF, off_str ); 

else 




menu text 

( menu 

adr. 

ONOFF, on str ); 

menu ienable ( 

| menu 

adr. 

SELECT1, on=!on ), 

menu ienable ( 

| menu 

adr. 

SELECT2, on ); 

menu ienable ( 

| menu 

adr. 

SELECT3, on ); 

break; 





case SELECT1: 

v_gtext ( handle, 20, 120, "Select 1 " ); 
break; 

case SELECT2: 

v_gtext ( handle, 20, 120, "Select 2 " ); 
break; 

case SELECT3: 

v_gtext ( handle, 20, 120, "Select 3 " ); 
break; 

} 

menu tnormal ( menu adr, msg buf[3], TRUE ); 

} 

} 

while ( msg buf[4] != QUIT ); 
menu_bar ( menu adr, FALSE ); 

} 

} 
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CHAPTER 17 - WINDOWS - PART 1 - DRAWING 

So far, we've talked about dialog boxes (including alert boxes and file selector boxes) and menu bars. 
That leaves us with one important area of GEM we've yet to touch upon: windows. This is a complex 
subject, one that we'll need several chapters to cover. The subject of windows can get as complex as 
you'd like. There's almost no end to the ways we can use them. 

What Are Windows Really? 

We've all used them, but how many of us have sat down and thought about what a window really 
is? From the user's point of view, a window truly lives up to its name, allowing him to move a 
transparent opening over information that may be too lengthy to fit on his screen, giving him a 
glimpse at data stored somewhere beyond the borders of our desktop. 

But this "windowness" is just an illusion, the result of some programmer's tedious and careful work. 
A window is not a magical creation; it's just a box. 

Imagine, if you will, a child's slate on which you've written as many film titles as will fit. Now some 
guy comes up to you and says, "The movie I'm looking for isn't on that list. Let me see some more." 
So you take out your eraser, erase the slate, and chalk some more titles onto its surface. The man 
shakes his head, mumbles something like "Maybe it wasn't a movie after all," and tells you to put the 
slate down on a table with several others. He then points to a different slate and asks you to pick it 
up. On this one are written book titles. The man smiles (Gee, look! There's a piece of spinach in his 
teeth!) and points to the title Foundation and Earth by Isaac Asimov. You erase the slate, set it back 
on the table, then go to the library and retrieve the book. The end. 

Who's the bossy guy in the story? The user, of course. And "you" are the programmer, manipulating 
the "windows" in the manner the user requests. 

Okay, maybe windows are a little fancier than a chalk slate. They do have some extra parts (if we 
want to use them), such as sliders, movers, fullers, closers, etc., and GEM does provide a small 
amount of help with handling windows. But, for the most part, a window is just what I said before: a 
box - a box that you, the programmer, have to maintain in accordance with messages received from 
your program's user. 

Figure 1 shows all the components contained in a complete window. You can use any or all of these 
parts, depending on your application's needs. 

The Window Demo 

When you run this chapter's program, a simple window will come up on the screen. This window 
won't contain all of the parts shown in Figure 1; it will have only a title bar, an information bar, a 
mover bar (actually the same as the title bar), a fuller button and a closer button - the parts we're 
going to cover in this chapter. 
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FIGURE 1 - Window Components 

Clicking on the fuller button causes the window to fill the entire desktop workspace. Clicking it a 
second time will return the window to its previous size. If you place the mouse pointer on the mover 
bar, then press and hold the left button, you can drag the window to any location you like on screen - 
- even off the screen, if you want. However, if you do move part of the window off the screen, when 
you move it back again, you'll notice that the window's workspace isn't redrawn. We'll see why this 
happens in an upcoming chapter. 

When you're through experimenting, click on the closer button. The window closes, and you're 
returned to the desktop. 

Drawing a Window 

Now let's take a look at this chapter's program listing in detail and see how all this window stuff 
works. The function do_wndw() is where most of the fun takes place, so we'll start there. 

The first thing we must do is decide what our window's maximum allowable size will be. We can limit 
the size to anything we want, but, in most cases, a window's maximum size is equal to the desktop 
workspace. The desktop is actually a window itself, the workspace of which is all the area of the 
screen, excluding the menu bar. The size of this workspace, measured in pixels, varies with the 
resolution, so we need a way to find out what the actual coordinates are. Luckily, GEM provides us 
with a function that'll supply the information we need. The call below will return requested 
information about a window: 

wind get (w h, flag, &x, &y, &w, &h) ; 


Here, w_h is the window's handle (in the case of the desktop, the handle is always 0), the integer flag 
is a flag telling the function what information we want, and &x, &y, &w, and &h are the addresses 
where the returned information will be stored. What information is actually placed in these locations 
depends on the value of flag. To get the work area's rectangle, we need to make flag equal to 
WF_WORKXYWH, which is defined in the Megamax header file, GEMDEFS.H. 

The function wind_get() can provide us with much information about our window, including the size 
of the work area, the size of the entire window, the window's maximum allowable size, the previous 
window's size, the position or size of either the vertical or horizontal sliders, and the coordinates of 
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the first or next rectangle in the rectangle list (something we'll cover in another chapter). All the flags 
you need to request any of this information are already set up for you in the GEMDEFS.H header file 
that came with your compiler. 

Now, where were we? Oh, yes! To get the size of the desktop's work area (which we'll use as our 
window's maximum allowable size), our call to wind_get() should look like this: 

wind get(0,WF WORKXYWH,Sfullx,Sfully,Sfullw,Sfullh); 

Remember: window handle 0 is always the desktop. 

Now we know the maximum allowable size for our window, and we've stored that information in 
fullx (X-coordinate of the window's upper left corner), fully (Y-coordinate of the window's upper left 
corner), fullw (the window's width), and fullh (the window's height). Next, we need to generate the 
window, as well as get its handle. (A window's handle is its name; that way we can differentiate it 
from other windows that may also be in use.) We do this with the call: 

w handle=wind_create(PARTS,fullx,fully,fullw,fullh); 

Here, the integer w_handle will receive the window's handle (a negative value indicates that the 
window couldn't be opened), PARTS is a flag representing the components we want included in the 
window, and fullx, fully, fullw, and fullh are the window's maximum allowable size. A call to 
wind_create() does not actually draw the window; it only sets up the window in memory. 

In our sample listing, PARTS is defined as: 

NAME|CLOSER|FULLER|MOVER|INFO 

The definitions for these labels (and all the others needed for a complete window) are defined in the 
Megamax header file GEMDEFS.H as on the next page. 


Label 

NAME 

CLOSER 

FULLER 

MOVER 

INFO 

SIZER 

UPARROW 

DNARROW 

VSLIDE 

LFARROW 

RTARROW 

HSLIDE 


Value 

0x0001 

0x0002 

0x0004 

0x0008 

0x0010 

0x0020 

0x0040 

0x0080 

0x0100 

0x0200 

0x0400 

0x0800 


As you can see, each of the above values sets a particular bit in the flag. To select the parts you wish 
included in your window, you OR the appropriate values together. Though you may include as many 
or few of the parts as you need for your application, you should never include in a window parts you 
don't plan on handling in your code. It tempts the user to play around with things he shouldn't, even 
though, in most cases, it won't do any harm; only your program can actually change a window. 

Since we've included the title and information bars in our window, we need to tell GEM where the 
associated strings can be found. If we neglect to do this, we'll get unpredictable results; we may even 
end up staring at a row of bombs across our screen (nasty old things). The call below fits the bill 
nicely: 
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wind set(w handle, WF NAME, title, 0, 0); 

Here, w_handle is the window's handle, WF_NAME (defined in the Megamax header file 
GEMDEFS.H) is a value indicating the field we wish to change, title is the address of the string we 
want displayed, and the two Os are dummy arguments. 

Just as with wind_get(), wind_set() has many possible values for its flag (represented by WF_NAME in 
the above call), each of which lets you change one of your window's attributes, including the title or 
information text, the window's position, the window's components, the sliders' size or position, and 
whether or not the window is the topmost (active) window. All the flags for this function are defined 
in your GEMDEFS.H file. 

The above call takes care of the title bar. We must make another call to wind_set() for the 
information line. The call is exactly as above except you would replace WF_NAME with WFJNFO and 
title with a pointer to the window info string. 

Now we're ready to actually bring the window up on the screen. First, we make a call to draw the 
animated, expanding box: 

graf growbox(startx, starty, startw, starth,endx,endy,endw,endh); 

Here, the integers startx, starty, startw, and starth are the X- and Y-coordinates of the upper-left 
corner and the width and height, respectively, of the box's starting rectangle. The integers endx, 
endy, endw, and endh are the equivalent values for the box's ending rectangle. 

The call below opens and draws a window: 

wind open (w h, x, y, w, h) ; 

Here, w_h is the window's handle, and the integers x, y, w, and h are the X- and Y-coordinates of the 
upper-left corner and the width and height of the window, respectively. You can open the window to 
any size less than or equal to the maximum you set with the wind_create() call. 

Next, we call our own function, draw_backgrd(), to fill in the new window's work area. The call to 
wind_open() actually draws only the window's borders and whatever parts we requested when we 
created the window. The work area is the programmer's responsibility. It's there for us to do with it 
what we like. 

Let's follow the flow of the program now by taking a look at the function draw_backgrd(). First, we 
turn off the mouse so the pointer doesn't interfere with our drawing. Then we call wind_get(), as we 
did before, to get the coordinates and size of the work area of the window we just opened. Now that 
we know this information, we simply draw a filled rectangle at the coordinates returned. A piece of 
cake! 

Handling a Window 

Okay, our window's on the screen. Now what do we do with it? We get information about what the 
user is doing with our window the same way we did with menu bars — through messages. Since 
we're interested only in one type of message in the sample program, we're not going to bother with 
that bulky evnt_multi() call. There's an easier way: 
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evnt mesag(msg buf); 

This call allows us to wait for messages without all of evnt_multi()'s extra and burdensome baggage. 
Here, msg_buf is the address of a 16-byte buffer where the message will be stored. Every time the 
user does something with our window, evnt_mesag() will notify us. 

The messages we'll receive are limited to those generated by the parts we included in our window 
when we created it. More specifically, in Listing 1, the only actions we're looking for are: the window 
was moved, the fuller button was clicked or the close button was clicked. 

When one of these actions occurs, a message is written to our message buffer. The first word, 
msg_buf[0], will contain the message type received. We'll use this value in a switch statement to 
choose the appropriate action. 

Window Moved 

If the window is moved, we'll receive a WM_MOVED (defined in the Megamax GEMDEFS.H file) 
message, telling us we have to reposition the window. The handle of the window moved will be 
found in msg_buf[3]. The coordinates and size will be found in msg_buf[4] through msg_buf[7] (X, Y, 
W and H, respectively). We move the window with the call: 

wind set(msg buf[3], WF_CURRXYWH, 

msg_buf[4],msg_buf[5],msg_buf[6], msg_buf[7]); 

The label WF_CURRXYWH is defined in the Megamax GEMDEFS.H file and tells wind_set() that we 
want to change the current window's coordinates, automatically moving the window to the new 
position. 

What if the user moved the window and we ignored the message by not calling wind_set()? The user 
would be able to move the window's outline around the screen all he wanted, but as soon as he 
released the button, the outline would vanish, leaving the window in its original location. 

Full Size or Previous Size? 

Another message we might receive in our sample program is WM_FULLED message. We get this 
message when the user clicks on the fuller button, at which time we must either expand the window 
to its maximum size or, if it's already at its maximum, return it to its previous size. It's up to the 
programmer to figure out which size is the right one. 

The first thing we do is call our own function, full_wind(), to set full_flag to its proper state. All 
full_wind() does is get the coordinates of the current and full-size windows and compare them. If any 
of the current coordinates don't match the full-size coordinates, we know that the window is not at 
its maximum, and we return a value of TRUE. If all the coordinates match, we're already at maximum 
and need to set the window back to its previous size. We signal this by setting our flag to FALSE. 

If we need to reduce the window to its old size, we first need to know the original coordinates. A call 
to wind_get(), where the second argument is WF_PREVXYWH takes care of that. Once we have the 
old coordinates, we call: 

graf shrinkbox(startx, starty, startw, starth, endx, endy, endw, endh); 

to animate the shrinking box (the parameters are the same as for graf_growbox()), then reposition 
the window with wind_set(). 
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The process of setting the window to its full size is similar, except we draw an expanding box instead 
of a shrinking one and use the full-size coordinates for the call to wind_set(). Also, when expanding 
the window to its maximum, we have to perform a window redraw (in this case, it's just a matter of 
drawing that rectangle in the work area). 

Closed For Business 

Now, all we have to do is provide a way for the user to get out of our program. The window's close 
button is perfect for this. When the user clicks it, we'll receive a WM_CLOSED message, which will 
cause us to exit our do/while loop. 

When we exit the loop, we find the coordinates of the current window with a call to wind_get(). Then 
we use those coordinates in a call to graf_shrinkbox(). To get rid of the window, we must first close it 
with the call: 

wind close(w handle); 

Here, the integer w_handle is the window's handle. Then we must remove the window from memory 
with the call: 

wind delete(w handle); 


More to Come 

In the following chapters, we'll learn what to do with redraw messages, how to handle sliders and 
arrows, and how to deal with multiple (gasp!) windows. Betcha can't wait, huh? 


Port: HYPertext by Lonny Pursell & PDF by DrCoolZic (jig) - VI.0 Oct. 2010 


Page 165/ 321 


C-MANSHIP COMPLETE - by CLAYTON WALNUT 


Program Listing #1 

j •k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k J 

/* C-manship, Listing 1 */ 

/* CHAPTER 17 */ 

/* Developed with Megamax C */ 

j •k'k-k-k-k-k-k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k'k-k'k-k-k-k-k-k-k-k-k-k'k-k-k-k'k J 

#include <osbind.h> 

#include <gemdefs.h> 

#include <obdefs.h> 

#define TRUE 1 
#define FALSE 0 

#define PARTS NAME|CLOSER|FULLER|MOVER|INFO 

/* The usual required GEM global arrays */ 

int work in [ 11], 

work_out[57], 

pxyarray[10], 

contrl[12], 

intin [12 8], 

ptsin[128], 

intout[128], 

ptsout[128]; 

/* Global variables */ 

int handle, dum, fullx, fully, fullw, fullh, 
curx, cury, curw, curh, oldx, oldy, oldw, oldh; 

int msg_buf[8]; 


*/ 

*/ 

*/ 

*/ 

*/ 


char *title = "C-manship - Chapter 17"; 


char *info = "Learning about 


main () 

{ 

appl_init (); /* 

open_vwork (); /* 

do_wndw(); /* 

v_clsvwk (handle); /* 
appl_exit (); /* 

} 


windows" ; 


Initialize application. 

Set up workstation. 

Go do the window stuff. 
Close virtual workstation. 
Back to the desktop. 


open vwork () 

{ 

int i; 

/* Get graphics handle, initialize the GEM arrays and open */ 
/* a virtual workstation. */ 

handle = graf_handle ( &dum, &dum, &dum, &dum); 
for ( i=0; i<10; work in[i++] = 1 ); 
work in[10] = 2; 

v_opnvwk ( work in, Shandle, work-out ); 

} 


do wndw () 
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int w_handle, full_flag; 

/* Find the size of the desktop's (handle 0) work area. */ 
wind get ( 0, WF WORKXYWH, Sfullx, Sfully, Sfullw, Sfullh ); 

/* Create window in memory. */ 

w handle = wind_create ( PARTS, fullx, fully, fullw, fullh ); 

/* Set the window's title and info text. */ 
wind set ( w handle, WF NAME, title, 0, 0 ); 
wind set ( w handle, WF_INFO, info, 0, 0 ); 

/* Draw the window on the screen. */ 
grafgrowbox ( 10, 10, 10, 10, 50, 50, 250, 200 ); 
wind_open ( w_handle, 50, 50, 250, 150 ); 
draw backgrd ( w handle ); 

/* Change mouse to arrow. */ 
graf mouse ( ARROW, 0L ); 

/* Receive event messages until the closer is clicked. */ 
do { 

evnt^mesag ( msg buf ) ; 

switch ( msg_buf[0] ) { /* msg_buf[0] is message type. 

/* If window is moved, set window at new 
location found in msg buf[4] through 
msg buf[7]. The handle of the 
window moved is in msg bug[3]. */ 

case WMJMOVED: 

wind set ( msg buf[3], WF_CURRXYWH, msg buf[4], 
msg_buf[5], msg_buf[6], msg_buf[7] ); 
break; 

/* If the fuller button has been clicked, set window to 
appropriate size based on full flag. */ 

case WM^FULLED; 

full flag = full wind ( w handle ); 
if (~!full_flag ) { 

wind_get ( w_handle, WF_PREVXYWH, 

Soldx, &oldy, &oldw, &oldh ); 

graf_shrinkbox ( oldx, oldy, oldw, oldh, 

fullx, fully, fullw, fullh ); 
wind set ( msg buf[3], WF CURRXYWH, 
oldx, oldy, oldw, oldh ); 

} 

else { 

wind_get ( w_handle, WFJ2URRXYWH, 

Scurx, Scury, Scurw, &curh ); 

graf_growbox ( curx, cury, curw, curh, 

fullx, fully, fullw, fullh ); 

wind set ( msg buf[3], WF CURRXYWH, 

fullx, fully, fullw, fullh ); 

draw backgrd ( w handle ); 

} 

break; 

} 

} 
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while ( msg buf[0] != WM_CLOSED ); 

/* Get current size of window for use in graf_shrinkbox, */ 

/* then close and delete the window. */ 

wind get ( w handle, WF_CURRXYWH, Scurx, &cury, Scurw, &curh ); 
graf_shrinkbox ( 10, 10, 10, 10, curx, cury, curw, curh ); 

wind_close ( w handle ); 
wind delete ( w handle ); 

} 


/* This function calculates if the window should be drawn to */ 

/* its maximum size or reset to its previous size. */ 

full wind ( w h ) 
int w h; 

{ 

int c_x, c_y, c_w, c_h, 
fx, fy, fw, fh; 

wind_get ( w h, WF_CURRXYWH, &c_x, &c_y, &c_w, &c h ); 
wind get ( w h, WF FULLXYWH, &f x, &f_y, &f w, &f h ); 
if ( c_x != f _x || c_y != f _y || c_w != f_w || c_h != f_h ) 
return ( TRUE ); 

else 

return ( FALSE ); 

} 


/* This function draws a white background in a window's */ 

/* work area. w_h is the window's handle. */ 

draw backgrd (w h) 
int w h; 

{ 

int wrk x, wrk_y, wrk w, wrk h; 
int pxy[4]; 

/* Turn off mouse for all drawing operations. */ 
graf mouse ( M_OFF, 0L ); 

/* Get the size of the window's work area. */ 

wind get ( w h, WF WORKXYWH, Swrk x, &wrk_y, &wrk w, Swrk h ); 

/* Set the color and fill style. */ 
vsf interior ( handle, 1 ); 
vsf color ( handle, WHITE ); 

/* Draw the rectangle in the window work area. */ 

pxy[0] = wrk x; 

pxy[l] = wrk y; 

pxy[2] = wrk x + wrk^w - 1; 

pxy[3] = wrk y + wrk h - 1; 

vr recfl ( handle, pxy ); 

/* Drawing over, so turn mouse back on. */ 
graf^mouse ( M_ON, 0L ); 

} 
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CHAPTER 18 - WINDOWS - PART 2 - SIZING 

In our last gem experiments, we learned some of the basic functions used to manipulate windows. 
We discovered how to initialize, open and close a window, as well as draw its interior (the work 
area), and handle the messages GEM sends to our application when the user wishes to move the 
window or make it full-size. 

As I'm sure you've guessed, there's still more to learn before we can call ourselves window experts -- 
much more. We still need to know how to handle many other types of window messages, not the 
least of which is the redraw message. We also need to know how to use the window's sizer button, 
scroll bars and arrow buttons. And then there's the matter of multiple windows! 

In the next couple of chapters, we'll tackle all of the above topics, giving you a fairly complete 
understanding of programming with windows. 

The Demo Program 

When you run this chapter's program, a full-screen window containing some text will be opened. You 
can drag the window around the screen by placing the mouse pointer on the title bar and holding 
down the left button. You can change the size of the window, using the mouse to click and drag on 
the sizer button. When you're through experimenting with the window, exit the program by clicking 
the closer button. 

It doesn't seem as if there's much more going on here than in Chapter 17's program, does it? But 
there is...there is... 

Any Size You Like 

The GEM window form provides a button that is used to set a window to any size the user requests. 
When the user activates the sizer button (by click/dragging it), an outline of the window appears on 
the screen. The outline expands and contracts with the movement of the mouse pointer — as long as 
the left button is held down. The moment the button is released, the window is redrawn at the size 
selected by the outline. 

Handling the sizer button is simple (well, there are a couple of complications that we'll get to in a 
minute). First, of course, when initializing the window, you must tell GEM to include the sizer button 
in its parts list. Then it's just a matter of waiting for the WM_SIZED message and using the call: 

wind set(msg buf[3], WF_CURRXYWH, 

msg_buf[4], msg_buf[5], msg_buf[6], msg_buf[7]); 

This sets the window's current size to that returned in the message buffer. (If you've forgotten how 
this message stuff works, review the last couple of chapters.) Easy. 

However, (have you noticed that there's always a "however"?) there are two things we have to 
watch out for. The first is a redraw message. We will receive one of these when the window is moved 
from a partially off-screen position back to the desktop, or when it's increased in size, either 
horizontally or vertically. Also, it's up to us, the programmers, to keep the size of a window within 
certain limitations. 

The maximum size of a window really isn't a problem. The window will never be larger than the 
desktop, anyway. It's just nice to know that, if we ever decide we want the window kept below a 
certain maximum size, we can. 

The minimum size, however, is important. If we don't check the requested size of the window before 
setting it, we may find we've left the user with a tiny, unusable blob on the screen. It's the 
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programmer's responsibility to make sure the window isn't set to a size too small to contain the parts 
it needs to function. 

Take a look at the do_wndw() function in Listing 1. It's here that we handle the messages GEM sends 
us. You'll notice that both WM_MOVED and WM_SIZED messages are dealt with the same way, via a 
call to our function do_move(). The reason is that both these window events are handled with the 
wind_set() call. 

In the function do_move(), the first thing we do is check the requested window size, returned to us in 
msg_buf[4] through msg_buf[7]. If the height or width of the requested window is smaller than the 
minimums we've set (the actual values can be found in the #defines at the top of the listing), we 
replace the unacceptable values with our minimum values. The user can try to set the window as 
small as he likes, but it will never be drawn at a size smaller than our minimum. 

If we need to control the window's maximum size, we would do it the same way, adding another set 
of if statements to check for compliance with whatever maximum values we wished to force on the 
window. 

Redraw Messages 

As we move our window around the screen, and as long as we stick to certain limitations, GEM is 
perfectly happy to redraw the window and its contents for us. But there are times when GEM stops 
right in its tracks, scratches its silicon head and says, "Here! You figure it out!" To understand why 
this happens, we need to know a little about how GEM does its window tricks. 

Basically, GEM has no trouble redrawing a window's contents (its work area), as long as all the data 
needed is present on the screen. For instance, let's say we've drawn a small window in the center of 
the screen and filled Vx'Ework area in with a white background. Now we move that window a little to 
the right. GEM can redraw the window because all the information it needs is still on the screen. 
When it does the redraw, all it does is "blit" the old screen information to its new location. The 
complication begins when we do one of two things with our window: move it on to the screen from a 
partially off-screen position, or enlarge it. 

In both of the above cases, as I'm sure you can see, the information GEM needs to redraw the 
window isn't available on the screen. GEM will make the attempt and redraw as much information as 
it can, but when it gets to the missing data, it'll give up and tell us to handle it, by sending a redraw 
message. 

This description is, of course, an over simplification. Things get much more complicated when you 
start dealing with multiple windows, since any movement of the active window (the topmost 
window) will surely result in redraw messages for some or all windows underneath. 

Redrawing a window is not, unfortunately, a simple process. To do it properly, you must perform the 
following steps: 

Step 1 Lock the window for an update. 

Step 2 Get the first rectangle to be redrawn from the rectangle list. 

Step 3 Check whether the rectangle returned from the redraw message (stored in 
msg_buf[4] through msg_buf[7]) intersects the rectangle obtained from the 
rectangle list. 

Step 4 If there's an intersection, set the clipping rectangle equal to the rectangle obtained 
from the rectangle list, and redraw the window. 

Step 5 Get the next rectangle from the rectangle list. 
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Step 6 Perform steps 3 through 5 until the rectangle list is empty (width and height both 
equal to 0). 

Step 7 Unlock the window. 

Sound like fun? Let's take an in-depth look at each step. 

Lock the Window 

The first thing we must do before updating a window is lock it away from GEM. This prevents the 
user from doing anything to "pollute" the screen — such as activating the menu bar or a desk 
accessory — while we're trying to get the window redrawn. Essentially, it stops two applications from 
writing to the screen at the same time. To lock a window, we use the call: 

wind update ( BEG UPDATE ); 

The integer BEG_UPDATE (defined as 1) tells GEM we're going to start updating the window and that 
other writes to our window should be disallowed. The wind_update() call also supports three other 
functions, depending on the value of the flag. The four flags and their values as defined in the 
GEMDEFS.H header file are as follows: 


ENDJJPDATE 

0 

Unlock window 

BEGJJPDATE 

1 

Lock window 

ENDJMCTRL 

2 

Lock mouse control 

BEGJMCTRL 

3 

Begin mouse control 


The Rectangle List 

In order to facilitate redrawing, GEM divides each window into a series of complete rectangles, then 
stores the coordinates of these rectangles in a rectangle list. We'll be discussing the rectangle list in 
greater depth in Chapter 19, when we start working with multiple windows; for now, it's enough to 
say that each time we get a redraw message, we must read each rectangle in the list, compare it to 
the rectangle returned from the redraw message, and redraw those rectangles that need updating. 

In Listing 1, the function do_redraw() demonstrates how to handle the rectangle list. We get the first 
rectangle in the list with the call: 

wind get(msg buf[3],WF FIRSTXYWH,&x,&y,&w,&h); 

Here, the integer msg_buf[3] is the window's handle (returned from the redraw message) and &x, 
&y, &w, and &h are the addresses of integers in which the coordinates of the rectangle will be 
stored. The flag WF_FIRSTXYWH is defined as 11 in the GEMDEFS.H file. 

We know we're at the end of the rectangle list when both w and h are 0. So, after getting the first 
rectangle, we enter a while loop that tests for this condition. 

Once we have a rectangle, we must test to see if it lies within the "dirty" area of the screen (usually 
the full area of the window that generated the redraw message). We use the call: 

rc_intersect( reel, rec2 ); 

Here, reel and rec2 are pointers to data of type GRECT. This returns a 1 if the rectangles intersect 
and a 0 if they don't. GRECT is defined in the GEMDEFS.H file and is nothing more than a structure 
consisting of four integers: the X- and Y-coordinates of the rectangle, and its width and height. 
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The Clipping Rectangle 

If the two rectangles intersect, we've found an area of the screen that must be redrawn. In order to 
be sure the data we're going to write doesn't overflow its area, we set a clipping rectangle. 

A clipping rectangle confines all writing to a specific portion of the screen. Anything that we try to 
draw outside of this area will be "clipped" off. Once we've set a clipping rectangle, we don't have to 
worry about figuring out exactly what to draw and where; we just redraw the entire window and let 
the clipping function do the hard part. To set a clipping rectangle, we use the call: 

vs_clip( handle, flag, pxy ); 

Here, handle is our application's handle; flag is an integer that, when FALSE (0), turns clipping off, 
and, when TRUE (1), turns clipping on; and pxy is a pointer to an array of four integers where the 
coordinates of the upper-left and lower-right corners of the clipping rectangle have been stored. 

See a small problem? The rectangle we want to redraw is given to us in the usual AES form of X, Y, 
width, and height; yet the clipping rectangle must be set using the VDI type of rectangle form. That's 
why, in our function set_clip(), we first have to do some simple conversions. 

Once the clipping rectangle is set, we just redraw the window's interior, letting the clipping function 
figure out where and where not to place data. When we're through updating the window, we call 
vs_clip() a second time with flag set to FALSE to turn off clipping. 

Emptying the Rectangle List 

In order to be sure we've updated the entire screen (wherever it needed it), we must "walk the 
rectangle list." That is, check every rectangle in the list against the rectangle returned from the 
redraw message. To get the remaining rectangles in the list, we use the call: 

wind get(msg buf[3],WF FIRSTXYWH,&x,&y,&w,&h); 

The parameters here are the same as for the call we used to get the first rectangle, except that the 
flag is now WF_NEXTXYWH, which is defined as 12 in the GEMDEFS.H file. 

We continue pulling rectangles from the list and redrawing them, if necessary, until the width and 
height values we get are both 0. At that point, we know we've checked all the rectangles. Once we've 
completed the rectangle list, the only thing left to do is unlock the window with the call: 

wind_update( ENDJJPDATE ); 


Something of Interest 

At the top of Listing 1, we've defined the text we need for our window work area like this: 

char *text[] = { 

"This is some sample text", 

"for use in the C-manship", 

"window demonstration found", 

"in Chapter 18." 

} ; 

This is a way to simulate string arrays in C. The array text[] is actually an array of pointers to 
character, each containing the address of one of the strings found within the quotes. The element 
text[0] contains the address of "This is some sample text"; element text[l] contains the address of 
"for use in the C-manship," and so on. 
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In Listing 1, the function draw_interior() shows how to access this array to print the text to the 
window. We simply use a for loop to advance through each element of the array, while in each 
iteration of the loop, we use the current array element as an argument to v_gtext(). 

The Agenda 

That's enough book work for now. Next time around, we'll look at some sample code for handling 
more than one window at a time. We'll also dig deeper into this confusing rectangle business. And, 
who knows? Maybe we'll find some other trouble to get into, as well. 
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Program Listing #1 

j •k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k J 

/* C-manship, Listing 1 */ 

/* CHAPTER 18 */ 

/* Developed with Megamax C */ 

/ •k'k-k'k-k-k-k'k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k'k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k J 

#include <gemdefs.h> 

#include <obdefs.h> 

#define TRUE 1 
#define FALSE 0 

#define PARTS NAME|CLOSER|MOVER|SIZER 
#define MIN_WIDTH 64 
#define MIN_HEIGHT 64 

/* GEM global arrays */ 
int work in[11], 
work_out[57], 
pxyarray[10], 
contrl[12], 
intin[128], 
ptsin[128], 
intout[128], 
ptsout[128]; 

/* Global variables */ 

int handle, fullx, fully, fullw, fullh, wrkx, wrky, 
wrkw, wrkh, curx, cury, curw, curh, w handle, 
char^w, char_h, box w, box h; 

int msg_buf[8]; 

char *title = "C-MANSHIP #17"; 

char *text[] = { 

"This is some sample text", 

"for use in the C-manship", 

"window demonstration found", 

"in Chapter 18." 

} ; 

int num_lines = 4; 

main () 

{ 

appl_init (); 
open vwork (); 
do_wndw(); 
v_clsvwk (handle); 
appl_exit (); 

} 


/* Initialize application. */ 
/* Set up workstation. */ 
/* Go do the window stuff. */ 
/* Close virtual workstation. */ 
/* Back to the desktop. */ 
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open vwork () 

{ 

int i; 

/* Get graphics handle, initialize the GEM arrays and open */ 
/* a virtual workstation. */ 

handle = graf_handle ( Schar^w, &char_h, &box_w, &box h); 
for ( i=0; i<10; work in[i++] = 1 ); 
work in[10] = 2; 

v_opnvwk ( work in, Shandle, work-out ); 

} 


do_wndw () 

{ 

/* Initialize and open our window. */ 
open window(); 

/* Change mouse to arrow. */ 
graf mouse ( ARROW, 0L ); 

/* Receive event messages until the closer is clicked. */ 
do { 

evnt_mesag ( msg_buf ); 

switch ( msg_buf[0] ) { /* msg_buf[0] is message type. */ 

case WM_MOVED: 
case WM^SIZED: 

do_move(); 
break; 

case WM REDRAW: 

do_redraw ( (GRECT *) &msg_buf[4] ); 
break; 

} 

} 

while ( msg buf[0] != WM_CLOSED ); 

/* Close and delete the window. */ 
close_window(); 

} 


do^move() 

{ 

/* Set window at new location. Also disallow any */ 

/* window sizes less than our minimum allowable size. */ 


} 


if ( msg_buf [ 6 ] < MINJATIDTH ) 
msg_buf[6] = MIN_WIDTH; 
if ( msgJouf[7] < MIN_HEIGHT ) 
msg_buf[7] = MIN_HEIGHT; 
wind set ( msg buf[3], WF_CURRXYWH, 

msg_buf[4], msg_buf[5], msg_buf[6], msg_buf[7] ); 
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draw interior ( clip ) 

GRECT clip; 

{ 

int pxy[4], y, x; 

/* Turn mouse off prior to drawing. */ 
graf^raouse ( M_OFF, OL ); 

/* Calculate clip rectangle and turn clipping on. */ 
set_clip ( TRUE, clip ); 

/* Get coordinates of window's work rectangle. */ 
wind get ( w handle, WF WORKXYWH, Swrkx, Swrky, Swrkw, 

/* Set the color and fill style. */ 
vsf interior ( handle, 1 ); 
vsf color ( handle, WHITE ); 

/* Draw the background in the window's work area. */ 

pxy[0] = wrkx; 

pxy[l] = wrky; 

pxy[2] = wrkx + wrkw - 1; 

pxy[3] = wrky + wrkh - 1; 

vr recfl ( handle, pxy ); 

/* Write the text to the window. */ 

y = wrky + box h; 

for ( x=0; x<num lines; ++x ) { 

v gtext ( handle, wrkx+8, y, text[x] ); 
y += box_h; 

} 

/* Drawing over, so turn the clipping */ 

/* off and turn the mouse back on. */ 

set_clip ( FALSE, clip ); 
graf_mouse ( M_ON, OL ); 

} 


do_redraw ( reel ) 

GRECT *recl; 

{ 

GRECT rec2; 

/* Lock window for update. */ 
wind update ( BEG UPDATE ); 

/* Get first rectangle from list. */ 
wind_get ( msg_buf[3], WF_FIRSTXYWH, 

&rec2.g_x, &rec2.g_y, &rec2.g_w, &rec2.g_h ); 

/* Loop through entire rectangle list, */ 

/* redrawing where necessary. */ 

while ( rec2.g w && rec2.g h ) { 

if ( rc^intersect ( reel, &rec2 ) ) 

draw interior ( rec2 ); 
wind get ( msg buf[3], WF^NEXTXYWH, 

&rec2.g_x, &rec2.g_y, &rec2.g_w, &rec2.g_h 

} 

/* Unlock window after update. */ 
wind_update ( END_UPDATE ); 

} 


Swrkh); 
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set_clip ( flag, rec ) 
int flag; 

GRECT rec; 

{ 

int pxy[4]; 

/* Convert rectangle to pxy coords. */ 

pxy[0] = rec.gx; 

pxy[l] = rec.g_y; 

pxy[2] = rec.g x + rec.g w - 1; 

pxy[3] = rec.g_y + rec.g_h - 1; 

/* Turn clipping on or off. */ 
vs^clip ( handle, flag, pxy ); 

} 


open window() 

{ 

/* Find the size of the desktop's work area. */ 

wind get ( 0, WF WORKXYWH, Sfullx, Sfully, Sfullw, Sfullh ); 

/* Create window in memory. */ 

w handle = wind_create ( PARTS, fullx, fully, fullw, fullh ); 

/* Set the window's title. */ 

wind set ( w handle, WF_NAME, title, 0, 0 ); 

/* Draw the window on the screen. */ 

graf_growbox ( 10, 10, 10, 10, fullx, fully, fullw, fullh ); 

wind^open ( w_handle, fullx, fully, fullw, fullh ); 

} 


close window() 

{ 

/* Get current size of window for use in graf^shrinkbox, */ 

/* then close and delete the window. */ 

wind get ( w handle, WF_CURRXYWH, Scurx, Scury, Scurw, Scurh); 
graf_shrinkbox ( 10, 10, 10, 10, curx, cury, curw, curh ); 

wind_close ( w_handle ); 
wind delete ( w handle ); 

} 
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CHAPTER 19 - WINDOWS - PART 3 - THE RECTANGLE LIST 


I'd wager that you're a little perplexed about the rectangle handling that we started discussing in 
Chapter 18. Don't feel bad. Not only is it a complex topic, but it's also virtually impossible to find 
complete documentation on it anywhere. Most of the books I've seen merely gloss over the subject, 
as if the reader were born with an intimate knowledge of GEM's rectangle list. 

Well, friends and neighbors, I, for one, was not born with that knowledge. I spent a month in 
research, trying to dig out all the facts I could about rectangle lists, not only because I wanted to 
clarify the issue for myself, but because I wanted to put together a decent tutorial to help you, the 
reader, understand this mysterious process. This chapter's program is based on what 

I've discovered. 

Rectangles Revealed 

In the course of my research, I spoke with Frank Cohen of Regent Software, and he told me that one 
method he used to sort out this rectangle nonsense was to update each rectangle returned from the 
redraw message with a different fill pattern. I told him I thought that idea was sheer genius (well, 
slightly clever, anyway), and as soon as I hung up the phone, I set about stealing his idea. 

Steal it, I did (with his blessings, I 
hope). The demo program at the end 
of this chapter uses Frank's method to 
graphically illustrate the process of 
walking the rectangle list. Figures 1 
through 12 take you step by step 
through the following tutorial. These 
screens were taken from a 
monochrome monitor, so if you have a 
color system, you may get slightly 
different results. 

When you run the program, you'll first 
see the screen shown in Figure 1. 

Three windows have been opened, 
and, since the windows need to have 
their work areas drawn, GEM has sent 
the program three redraw messages, one for each window. Because I inserted a call to CconinQ in 
the rectangle list processing loop, nothing further will happen until you press Return. 

But before we let GEM do its thing, take a look at the top line of the screen. Fiere you'll see the 
handle of the window for which the redraw message was sent and the number of the rectangle from 
the rectangle list we're currently working on. In Figure 1, we see that window 1 is waiting for a 
redraw, and that we're about to process rectangle 1 from the list. 

We can't go blindly ahead and fill in window l's workspace because part of that space is covered by 
the other two windows; we don't want to erase them. For this reason, when GEM created the 
redraw message for window 1, it took that window's workspace (only those areas not covered by the 
other two windows) and divided it into a series of non-overlapping rectangles. It then loaded the 
coordinates and sizes of those rectangles into the rectangle list where we can get at them for 
processing. 

Now press Return once. The first rectangle from the list will be processed, the screen will be 
updated, and the program once again waits for a key press. But before we give it that key press, let's 
take a closer look at what happened with that first rectangle. 



Figure 1 
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If you think back to Chapter 18, you'll remember that, when processing the rectangle list, we're 
always dealing with two rectangles: one returned in the redraw message and one retrieved from the 
list. In the case of the rectangle we just processed, the rectangle received from the redraw message 
was window l's complete work area. The rectangle returned from the list was the one you just saw 
filled in (the light gray rectangle at the top of Figure 2). The first thing we had to do when we got 
these rectangles was check whether they overlapped. You'll remember that the call 

rc intersect( reel, rec2 ); 


accomplishes this for us. What I didn't 
mention in Chapter 18 was that, after 
the call, the rectangle found in rec2 
may not be the same one we started 
with; it'll actually be a rectangle 
representing the intersection of the 
two original rectangles. 

Now, do our first two rectangles 
intersect? Sure enough! We know 
we've found an area that must be 
updated, and we send the rectangle 
found in rec2 to draw_interior(), our 
actual drawing routine. Note that, in 
this case, the rectangle returned in 
rec2 was the same rectangle we 
started out with, because its entire 
area is in intersection with the one returned in the redraw message. 

Look at the information at the top of the screen. We're now ready to process rectangle 2 from 
window l's list. Press Return, and this area will be updated. Keep pressing Return, filling in each of 
window l's rectangles, until you hear the computer's bell ring, indicating you've reached the end of 
the rectangle list and completed the processing of the first redraw message. 

Now the information at the top of the screen will show that we're about to process a redraw 
message for window 2. Before you press Return, see if you can figure out how many rectangles it'll 
take to do the job (hint: nothing should be drawn in window 3's workspace). Figured it out? Everyone 
who guessed that we need to update two rectangles may look into a mirror and tell yourself how 
clever you are. Press the 
return key twice to update 
window 2. The bell should ring 
after the second press, leaving 
us ready to process the redraw 
message for window 3. 

How many rectangles for 
window 3? One. Window 3 is 
the topmost window, so has 
nothing covering it; we need 
only fill in the entire work 
area. 

Now your screen should look 
similar to Figure 2. Grab 
window 3 by the mover bar, 
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and drag it into the upper-right corner of the screen, as shown in Figure 3. Notice that, even though 
the image of the old window 3 is still 
on the screen, we didn't have to 
redraw the window in its new 
position. Since its complete image was 
on the screen, GEM did the job for us, 
blitting the image to its new location. 

After blitting the window image, GEM 
then redrew window 2, not including 
the workspace. Why not the 
workspace, too? Before we moved 
window 3, window 2 was partially 
hidden, so after the move, GEM didn't 
know what we wanted to put in the 
uncovered area. It happily dropped 
the whole mess -- including a 
rectangle list — into our laps. Our 
status line at the top of the screen now tells us that we've received a redraw message for window 2, 
and we're waiting to process rectangle 1. 


Now think for a minute. (Aw, come 
on, it won't hurt much.) What 
portion of window 2 is going to be 
redrawn when we press the return 
key? Any guesses? The entire work 
area, you say? Wrong! Why take the 
time to update the entire work area 
when only a small section — that that 
was covered by window 3 -- needs 
redrawing? Because it's easy? Well, 
yes, but it's just as easy to do it right, 
because, after our call to 
rcjntersect, we have the area of 
intersection — the exact rectangle we 
need — in rec2. Press Return to see 
this rectangle get its due. 



Figure 5 


Since GEM wants to get rid of the 
rest of window 3's old image, we 
now have a redraw message for 
window 1. Press Return. 
Hmmmmmm. Nothing happened. If 
you look at the rectangle number in 
our status display, though, you'll see 
that something did happen, because 
we're now on rectangle 2. So what 
happened to rectangle 1? We 
processed it just as all the others, but 
because it didn't intersect the dirty 
area (the rectangle returned in the 
redraw message) we skipped over it. 
If you look at the screen, you can see 



Figure 6 
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that rectangle didn't need to be 
redrawn. 

Continue pressing Return until the bell 
rings, watching to see which rectangles 
are redrawn and which are skipped. 
Your screen should end up resembling 

Figure 4. 

As you may recall, another way to 
generate a redraw message is to 
increase the size of a window. Grab 
window 2's sizer button and enlarge the 
window as shown in Figure 5. 
Predictably, a redraw message for 
window 2 is sent. How many rectangles 
this time? Only one. Sorry, but I guess it 



Figure 7 


was a trick question. Go ahead and 
press Return. The entire work area of 
window 2 is redrawn, leaving your 
screen looking like Figure 6. Strange, 
considering I just said it was a waste of 
time to redraw portions of a window 
that didn't need it. That top, left-hand 
corner didn't need to be redrawn, did 
it? The fact is, whenever you enlarge a 
window or make it uppermost, the 
rectangle returned in rec2 will be the 
entire work area. I never promised 
GEM was consistent. 

Next step in our experimentation: 
move window 2 to the lower, right 
corner of the screen, below window 3 
(not over-lapping). Then press Return 
until the bell rings, watching as window 
1 is updated. Figure 7 shows the 
results. Now click the mouse pointer on 
window l's workspace, making it 
uppermost. Press Return, and your 
screen will look like Figure 8. Using 
window l's sizer button, reduce the 
window to it's smallest size, as shown in 
Figure 9. 

Note that, when we reduced window 1, 
GEM cleaned up the desktop on its 
own, leaving only the work areas of 
windows 2 and 3 for us to worry about. 
As they stand now, both windows 2 and 
3 contain information left behind by 
window 1. Press Return twice to update 
both windows. 



Figure 8 



Figure 9 


Port: HYPertext by Lonny Pursell & PDF by DrCoolZic (jig) - VI.0 Oct. 2010 


Page 181/321 


























































































































































C-MANSHIP COMPLETE - by CLAYTON WALNUT 


Move window 1 around the desktop, 
without overlapping any of the other 
windows or going off screen. We get no 
redraw messages. GEM is delighted to 
blit window 1 from one place to 
another with no help from us. 


Now place window 1 in the center of 
window 2, as shown in Figure 10. Still 
no redraw messages. GEM blitted the 
window to its new location then erased 
the old image, just like before. Windows 
2 and 3 don't get redraw messages 
because none of their visible data has 
been corrupted. Sure, we covered some 
of it up, but that's not a problem until 
we move window 1 out of the way 
again. Do so now, as shown in Figure 
11. Whoops! GEM did the blit all right, 
but it left a mess behind. Press Return 
to conclude this fascinating journey 
through GEM's rectangle lists, leaving 
the screen shown in Figure 12. 
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Figure 11 


Hopefully, our experiment has taken 
some of the mystery out of GEM's 
rectangles and how the system 
works. Play around with the program 
all you want, moving and changing 
windows, all the while watching to 
see how GEM sets up its rectangle list 
and how the program processes it. 
There are an infinite number of 
possibilities. It'll be a long time 
before you exhaust them. 

If you want the program to run 
without waiting for a key press, 
remove the call to CconinQ found in 
the function do_redraw(). The 
information printed at the top of the 
screen won't do you much good if 
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Figure 12 


you do, though. You'll never be able to read it as fast as our program can update those rectangles. 
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Sidelines 

Before we close up shop for this chapter, there are a couple of things in Listing 1 we ought to go 
over. 

This is the first time we've handled the WM_TOPPED message in a program. We get this message 
from GEM whenever the user clicks the mouse over an inactive window. The call 

wind_set(msg_buf[3], WF_TOP, 0, 0); 

is all it takes to "top" the window, make it uppermost and active. Here, msg_buf[3] is, as usual, the 
window's handle; WF_TOP is the function we want wind_set() to perform, defined in GEMDEFS.H as 
10; and the two zeros are dummy arguments. 

Another nuance worthy of note is the way we're using arrays to cut down the window handling code 
in the program. Wherever we perform the same function concurrently on all windows, we can use a 
for loop, the control variable of which becomes an index into an array (one element for each 
window). 

If you look at the function open_window() in Listing 1, you'll see the loop that opens the windows 
and places their handles into the array w_h[]. We need only one set of wind_create() and wind_set() 
calls. However, when we actually open the windows, we use a separate wind_open() call for each 
window. Why? Because each window is opened at its own set of coordinates, and for the sake of 
clarity, I decided to "hardcode" those coordinates into the function calls rather than use arrays. 

Another Day, Another Dollar 

In Chapter 20 our subject will be...Yes! You guessed it. Windows, again. Maybe we'll figure out how 
to use those sliders and arrows to change the contents of a window's workspace. Sounds like a good 
idea to me. How about you? 

Program Listing #1 

j -k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k J 

/* C-manship, Listing 1 */ 

/* CHAPTER 19 */ 

/* Developed with Megamax C */ 

jkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkJ 

#include <gemdefs.h> 

#include <obdefs.h> 

#include <osbind.h> 

#define TRUE 1 
#define FALSE 0 

#define PARTS NAME|CLOSER|MOVER|SIZER 

#define MINJATIDTH 64 

#define MIN_HEIGHT 64 

#define PATTERN 2 

#define BELL 7 

#define HIGH 2 

/* GEM global arrays */ 
int work in[11], 
work_out[57], 
pxyarray[10], 
contrl [ 12] , 
intin[128], 


Port: HYPertext by Lonny Pursell & PDF by DrCoolZic (jig) - VI.0 Oct. 2010 


Page 183/321 



C-MANSHIP COMPLETE - by CLAYTON WALNUT 


ptsin[128], 
intout[128], 
ptsout[128]; 


/* Global variables */ 

int handle, fullx, fully, fullw, fullh, wrkx, wrky, 
wrkw, wrkh, res, char_w, char_h, box w, box h, fill; 
int msg_buf[8]; 
int w_h[3]; 

char *titles[] = {"#1", "#2", "#3"}; 


main () 

{ 

appl_init (); / 

open_vwork (); / 

do_wndw(); / 

v_clsvwk (handle); / 

appl_exit (); / 

} 


Initialize application. 

Set up workstation. 

Go do the window stuff. 
Close virtual workstation. 
Back to the desktop. 


*/ 

*/ 

*/ 

*/ 

*/ 


open vwork () 

{ 

int i; 

/* Get graphics handle, initialize the GEM arrays and open */ 
/* a virtual workstation. */ 

handle = graf handle ( Schar w, Schar h, &box w, &box h); 
for ( i=0; i<10; work in[i++] = 1 ); 
work in[10] = 2; 

v_opnvwk ( work-in, &handle, work-out ); 

} 


do_wndw () 

{ 

/* Clear screen. */ 
graf^mouse ( M_0FF, OL ); 
v_clrwk ( handle ); 
graf_mouse ( M_0N, OL ); 

/* Find screen resolution. */ 
res = Getrez(); 

/* Initialize and open our windows. */ 
open window(); 

/* Change mouse to arrow, and initialize fill style. */ 
graf^mouse ( ARROW, OL ); 
fill = 0; 

/* Receive event messages until the closer is clicked. */ 
do { 

evnt_mesag ( msg_buf ); 

switch ( msg_buf[0] ) { /* msg_buf[0] is message type. */ 

case WM_M0VED: 
case WM_SIZED: 

do^move() ; 
break; 


Port: HYPertext by Lonny Pursell & PDF by DrCoolZic (jig) - VI.0 Oct. 2010 


Page 184/321 


C-MANSHIP COMPLETE - by CLAYTON WALNUT 


case WM TOPPED: 

wind_set ( msg_buf[3], WF_TOP, 0, 0 ); 
break; 

case WM REDRAW: 

do_redraw ( (GRECT *) &msg_buf[4] ); 
break; 

} 

} 

while ( msg buf[0] != WM_CLOSED ); 

/* Close and delete the windows. */ 
close window(); 


do^move() 

{ 

/* Set window at new location. Also disallow any 
/* window sizes less than our minimum allowable size. 


} 


if ( msg_buf [ 6 ] < MINJATIDTH ) 
msg_buf[6] = MIN_WIDTH; 
if ( msgJouf[7] < MIN_HEIGHT ) 
msg_buf[7] = MIN_HEIGHT; 
wind set ( msg buf[3], WF_CURRXYWH, 

msg_buf[4], msg_buf[5], msg_buf[6], msg_buf[7] 


draw interior ( clip ) 
GRECT clip; 

{ 

int pxy[4], y, x; 


/* Turn mouse off prior to drawing. */ 
graf_mouse ( M_0FF, OL ); 

/* Calculate clip rectangle and turn clipping on. */ 
set_clip ( TRUE, clip ); 

/* Get coordinates of window's work rectangle. */ 
wind get(msg buf[3],WF WORKXYWH, Swrkx, &wrky, Swrkw, 


/* Set the color and fill style. */ 
vsf interior ( handle, PATTERN ); 
fill += 1; 
if ( fill>24 ) 
fill = 1; 

vsf_style ( handle, fill ); 
vsf color ( handle, BLACK ); 


/* 

Draw 

the background in 

pxy 

[0] = 

wrkx; 

pxy 

[1] = 

wrky; 

pxy 

[2] = 

wrkx + wrkw - 1; 

pxy 

[3] = 

wrky + wrkh - 1; 

vr 

reef 1 

( handle, pxy ); 


the window's work area. */ 


*/ 

*/ 


&wrkh); 
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/* Drawing over, so turn the clipping */ 
/* off and turn the mouse back on. */ 

set_clip ( FALSE, clip ); 
graf_mouse ( M_ON, OL ); 


do_redraw ( reel ) 

GRECT *recl; 

{ 

GRECT rec2; 
int rec_cnt, y; 

/* Init rectangle count, and set y coord for text. */ 
rec_cnt = 0; 
if ( res == HIGH ) 
y = 15; 

else 

y = 8; 

/* Lock screen for update. */ 
wind update ( BEG UPDATE ); 

/* Get first rectangle from list. */ 
wind_get ( msg_buf[3], WF_FIRSTXYWH, 

&rec2.g_x, &rec2.g_y, &rec2.g_w, 

/* Loop through entire rectangle list, 

/* redrawing where necessary, 
while ( rec2.g w && rec2.g h ) { 

test_print ( "handle", msg_buf[3], 150, y ); 
rec_cnt += 1; 

test_print ( "rec #", rec_cnt, 20, y ); 

Cconin(); 

if ( rc^intersect ( reel, &rec2 ) ) 

draw interior ( rec2 ); 
wind get ( msg buf[3], WF^NEXTXYWH, 

&rec2.g_x, &rec2.g_y, &rec2.g_w, &rec2.g_h ); 

} 

/* Unlock screen after update. */ 
wind_update ( END_UPDATE ); 

Cconout ( BELL ); 

} 


&rec2.g_h ); 

*/ 

*/ 


set_clip ( flag, rec ) 
int flag; 

GRECT rec; 

{ 

int pxy[4]; 

/* Convert rectangle to pxy coords. */ 

pxy[0] = rec.gx; 

pxy[1] = rec.g_y; 

pxy[2] = rec.g x + rec.g_w - 1; 

pxy[3] = rec.g_y + rec.g_h - 1; 

/* Turn clipping on or off. */ 
vs^clip ( handle, flag, pxy ); 

} 
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open window() 

{ 

int x; 

/* Find the size of the desktop's work area. */ 

wind get ( 0, WF WORKXYWH, Sfullx, Sfully, Sfullw, Sfullh ); 

/* Create the windows. */ 
for ( x=0; x<3; ++x ) { 

w h[x] = wind_create ( PARTS, fullx, fully, fullw, fullh ); 
wind_set ( w h[x], WF NAME, titles[x], 0, 0 ); 

} 

/* Draw the windows. */ 

wind open ( w_h[0], fullx, fully, fullw, fullh ); 
wind_open ( w_h[l], 50, 65, 100, 100 ); 
wind_open ( w_h[2], 100, 90, 100, 100 ); 

} 


close window () 

{ 

int x; 

/* Close and delete the windows. */ 
for ( x=0; x<3; ++x ) { 

wind_close ( w h[x] ); 
wind_delete ( w_h[x] ); 

} 

} 


test_print ( label, number, x, y ) 
int number, x, y; 
char *label; 

{ 

char t [100]; 

sprintf ( t , "%s = %d%s", label, number, " " ); 

v_gtext ( handle, x, y, t ); 

} 
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CHAPTER 20 - WINDOWS - PART 4 - SLIDERS AND ARROWS 


We've stated previously that a window is just a box that allows us to display data in a convenient 
manner, and the programmer is completely responsible for what is done with the window's work 
area. One of the things that GEM's windows provide, to help the user manipulate the displayed data, 
is the slider/arrow system. By moving the sliders or clicking the arrows, the user can "move" the data 
within the window to any position he likes. 

This convenience is paid for by the programmer, however, because, when a slider or arrow is used, 
GEM does nothing but send a message to the program. It's up to the programmer to decide what to 
do with the message and how to update the window's display. 

When this chapter's program is run, a window will be opened, the directory of the default drive (the 
one you ran the program from) will be read, and the filenames found there displayed in the window's 
work area. You may then use the sliders and arrows in their conventional way to move the data 
within the window. You can also enlarge or shrink the window by dragging (with the mouse, of 
course) the lower-right corner of the window. 

Note that the example program provides only the vertical arrows and sliders. I didn't include the 
horizontal ones because they're handled almost exactly the same way as their vertical counterparts. 

Getting a Directory 

The first item of interest in the sample program is the method with which we can read a disk's 
directory. The code to accomplish this can be found in the get_fnames() function in Listing 1. Let's 
take a look at that now. 

First, we must initialize a couple of variables. We'll be using the integer p as an array index, and the 
integer files.count (this is a member of the structure files, which is declared near the top of the 
listing) will contain the number of filenames read from the directory. 

Next, we set an important address with the call: 

Fsetdta( dta ); 

Here, dta is a pointer to character data (in our case, the address of the character array dta[]). The 
function FsetdtaQ is GEMDOS function Oxla and is declared in OSBIND.H. It sets the address of the 
DTA (Disk Transfer Address), a 44-byte buffer in which the directory data is stored. We supplied the 
buffer by defining the array dta[]. 

When we get around to actually reading a filename, the DTA will contain all sorts of useful 
information, as shown here: 


Byte 

Contains 

0-20 

For OS use only 

21 

File attribute 

22-23 

Integer, file time stamp 

24-25 

Integer, file date stamp 

26-29 

Long integer, file size 

30-43 

Filename 


So let's fill that DTA, shall we? We get the first filename with the call: 

end = Fsfirst( p, a ); 

Here, p is the pathname you want to use for the file search and a is an integer whose bit settings 
determine the search's attributes. The function call returns a negative integer in the case of an error 
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(for instance, when there are no more file-names to be read). In the sample listing, we placed the 
path-name string, directly into the call. This pathname takes advantage of "wild cards," so the 
search will match any file. 

The attributes set by a are determined as follows: 


Bit Result 

0 Search limited to normal files 

1 Read-only files included 

2 Hidden files included 

3 System files included 

4 Folder names included 

5 Subdirectory files included 


By setting bits 0 and 4 in the search attributes argument, we'll read all the file and folder names from 
the root directory (and, because of the pathname, these will be read from the default drive), just as if 
you had just opened the drive from the desktop. 

Now that we've got the first filename, we set up a while loop to get the rest, as well as to process the 
filenames into the form we need, later storing them into the two-dimensional array files.fnames[][j. 
All we're doing in the processing is making sure each entry in the filename array is exactly 15 
characters long: the filename padded with spaces and ending with a null. 

The rest of the filenames are retrieved, one by one, with the call: 

end = Fsnext (); 

This function (GEMDOS 0x4f), defined in OSBIND.H, also returns a negative value for an error 
condition. We continue executing the while loop until end becomes negative, or files.count becomes 
greater than MAX. 

Slipping and Sliding 

Now that we've got all those filenames stored, we're ready to open our window. We've done all this 
stuff before; there's nothing new here, except the use of the integer top to keep track of where in 
the filename list the window's data display is to start (remember, the topmost filename in the display 
won't necessarily be the first one in our list), and setting up the sliders. 

Once we open the window, we need to set the size and position of the slider. Our function calc_slid() 
takes care of this, and requires three integers as arguments: the handle of the window; the total 
number of text lines (in this case, the number of filenames in the list); and the total width of the text 
in columns. 

The function first calls wind_get() to get the size of the window's work area, then calculates the 
number of lines and columns that'll fit that area. The size of the slider is then calculated like this: 

size = 1000*lines avail/line_count; 

The size of the slider can range anywhere from 1 to 1000, and represents the relative portion of the 
document displayed. By dividing the number of lines available in the window by the number of lines 
in the "document," we end up with a value representing the portion of the document that'll fit the 
window. Multiplying this value by 1000 will give us the equivalent size of the slider. 
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For example, let's say we have 10 lines to display, but the window can hold only 6. Dividing 6 by 10 
gives us .6 — the portion of the document that the window can display. When we multiply this value 
by 1000, we get 600 — the slider's relative size. Keep in mind that, for greater accuracy, you might 
want to use floating-point math, rather than integer math. 

Once the size of the slider is calculated, it's set with the call: 

wind set(w h,WF_VSLSIZE,size,0,0,0); 

Here, w_h is the window's handle, WF_VSLSIZE is the function's operation flag (WF_HSLSIZE for 
horizontal sliders) as defined in GEMDEFS.H, size is an integer value between 1 and 1000, and the 
three zeroes are unused arguments. 

Next, we need to calculate the slider's position within its track, which is also a value between 1 and 
1000. The following calculation, done with floating-point math, the result of which is cast to an 
integer, does this: 

pos=(int)(float)top/(float)(line_cnt-lines_avail)*1000; 

The integer top is the number of the uppermost displayed line in the window, line_cnt is the total 
number of lines in the document, and lines_avail is the number of lines that'll fit the window. 

The slider's position is then set with the call: 

wind set(w h,WF_VSLIDE,pos,0,0,0); 

Here, w_h is the window's handle, WF_VSLIDE is the function's operation flag (WF_HSLIDE for 
horizontal sliders) as defined in GEMDEFS.H, pos is an integer between 1 and 1000, and the three 
zeroes are unused arguments. 

Me and My Arrow 

Whenever the user clicks on one of the arrows, or in the slider's tracks, the program will receive a 
WM_ARROWED message. This message is a little different from the others we've worked with. It 
actually contains a sub-message, which GEM stores in msg_buf[4]. This forces us to do a little more 
work before we can take care of the user's request. This extra work is tackled in the function 
do_arrow(), where we use the value stored in msg_buf[4] to determine exactly what the user wants 
to do. 

If the user has clicked on the down arrow, msg_buf[4] will contain a WA_DNLINE message, and 
program execution will continue with the function do_dnline(). 

Before we look at that function, let's stop and think about what we're doing. What exactly is the user 
requesting when he clicks on the down arrow? Generally, it means that we must move the 
window's display one unit upward and the slider one unit downward. Exactly what that "unit" is 
depends on your application. If our window contained some sort of graphic information, such as a 
map, a unit could be anything from a single scan line to dozens of scan lines. Luckily, our decision is a 
little easier. We're working with text, so the obvious unit of measurement is a text line. 

We know now what we want to do, but how are we going to go about it? The easy way of updating 
the display would be just to increment top, then call draw_interior() to redraw the window's work 
area. The problem with that is that it's too slow, too sloppy. We're going to need something much 
more elegant. 

When you're working with the desktop's file windows, the text displays move neatly upward one line 
each time you click on the down arrow; you can't see the redrawing. 


Port: HYPertext by Lonny Pursell & PDF by DrCoolZic (jig) - VI.0 Oct. 2010 


Page 190/321 


C-MANSHIP COMPLETE - by CLAYTON WALNUT 


Almost all the information we need is on the screen, right? Only the bottom of the new list isn't 
shown. You know what that means? We can update most of the window using raster operations. All 
we have to do is "blit" the area of the window from the second filename down to a position one text 
line higher, then fill in the bottom with the new filename. And that's exactly what we do in 
do_dnline. 

Let's run through that function now. First, we use wind_get() to get the size of the window's work 
area. Then we calculate the number of text lines that'll fit. Armed with that information, we use an if 
statement to make sure we don't bother updating the window if there are no filenames left to 
display. In other words, if the last file in our list is already shown in the window, we want to ignore 
the request to scroll downward. 

If our calculations show that the arrow message is okay to process, we increment top, calculate 
where in our list of filenames we'll find the new data that needs to be displayed, set clipping to on, 
turn off the mouse and do our raster stuff. 

Because -- depending on the size of the window — we may have a partial filename displayed at the 
bottom, we actually have to print two filenames, and if we're at the end of the list, the second 
filename should be a line of spaces. Here's what happens in our function: 

If the window is a size in which an even number of filenames will fit, our code will blit the display up 
one line, then print at the bottom the next two filenames in the list. The first will go at the very 
bottom line, and the second won't appear at all, because we're trying to print it outside of the 
clipping area. 

Now, let's take a case where the size of the window allows a partial filename to show at the bottom. 
When we do our calculations for the number of lines that'll fit the window, the result is an integer, 
which means the decimal portion has been truncated (i.e., rounded down to the nearest integer). 
Because of this, only the number of complete lines that'll fit the window are counted. That's why we 
always want to print two filenames, since the second may represent one that is only partially visible. 

In the case of a partially displayed filename, we'll actually have to print one and a half filenames. 
Sound tricky? Naw. The clipping rectangle makes this little complication easy to handle. We just print 
two filenames, and anything that lies outside of the area gets clipped off, leaving us with a partial 
filename (the second one we printed) at the bottom. 

Once we've gotten our display written, we have to recalculate the position of the slider. This is done 
the same way we did it when we first opened our window, with a call to our function calc_slid(). 

That completes the processing of the down-arrow request. The function do_upline() does the same 
thing for the WA_UPLINE message as do_dnline() did for the WA_DNLINE message, except the 
process is reversed — and a little simpler. 

In do_upline() we're rastering the window's work area down one line, then printing the next filename 
(thinking backwards) at the top. Because we'll never have a partial line here, we don't have the extra 
complications we had with do_dnline(). 

Paging All Sliders 

Two other messages we may receive from the original WM_ARROWED message (not including 
messages for horizontal sliders and arrows, which are WA_LFPAGE, WA_RTPAGE, WA_LFLINE, and 
WA_RTLINE) are WA_DNPAGE and WA_UPPAGE. These are sent to us by GEM whenever the user 
clicks in the slider's track, indicating that he wants the next "page" of information, the next 
windowful of lines following that already shown in the window. 

Because the information we want displayed in the window is not available anywhere on the screen, 
we can't use raster operations. We have to do it the sloppy way: figure out the new line for the top 
of the window, then call our function draw_interior() to do the work. But there are a couple of things 
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we have to watch out for when calculating the new top. We have to make sure that top doesn't end 
up less than zero and that it doesn't become a value that will cause our display to go beyond the 
bottom of our text. 

Let's look at the function do_dnpage(). First, we use a wind_get() call to find the size of the window's 
work area. Then we calculate the number of lines that'll fit. Since we want to move down that 
number of lines in the document, all we have to do to calculate the new value for top is to add 
lines_avail to its existing value. The only thing to check for is the bottom of the document. If our new 
top, plus the number of lines in the display equal a value greater than the total number of lines in the 
document, we have to set back the value of top in such a way that the last line of our document will 
also be the bottom line of the window. Not too tricky, really. 

The function do_uppage() (which executes when we receive a WA_UPPAGE message) works in the 
same manner, except we subtract lines_avail from top, then check to make sure top isn't less than 
zero. 

Anywhere You Like 

Another way the user can change the window's display is to grab the slider with the mouse pointer 
and move it to a new position. When this occurs we get a WM_VSLID message from GEM (or 
WM_HSLID, if it's a horizontal slider). 

This message is almost as easy to handle as the WA_UPPAGE and WA_DNPAGE messages. The key 
thing to know here is that the slider's new position is returned in msg_buf[4]. To find the 
corresponding position in our document, all we have to do is get the size of the window's work area, 
calculate the number of lines that'll fit the window, then perform the following calculation: 

top=msg buf[4] * (line_cnt - lines_avail) / 1000; 


We then set the slider to its new position with the call: 

wind set(w h,WF_VSLIDE,msg buf[4],0,0,0); 


A call to our function draw_interior() (which will use the new value calculated for top) completes the 
task. 


An Important Note 

You should be aware that, many times, the calculations for finding the size and position of the sliders 
may have to be done with 32-bit math (using long integers) to avoid overflow problems, or with 
floating-point math when you need greater accuracy. Ignoring these possibilities could give you some 
perplexing results. If ever you find your sliders behaving mysteriously — and you're sure your logic is 
correct -- check your math. 


Program Listing #1 

* * I 
*/ 
*/ 
*/ 

* * j 

#include <gemdefs.h> 

#include <obdefs.h> 

#include <gembind.h> 

#include <osbind.h> 


J •k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k'k 

/* C-manship, Listing 1 

/* CHAPTER 20 

/* Developed with Megamax C 

I'k'k'k'k'k'k'k'k'k'k'k'k'k'k-k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k'k 
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#define TRUE 1 
#define FALSE 0 

#define PARTS NAME|CLOSER|SIZER|UPARROW|DNARROW|VSLIDE 

#define MAX 50 

#define SOLID 1 

#define MIN_WIDTH 64 

#define MIN_HEIGHT 64 

/* GEM arrays. */ 
int work in [ 11] , 
work_out [57], 
contrl [ 12], 
intin[12 8] , 
ptsin [12 8] , 
intout[128], 
ptsout[128]; 

/* Global variables. */ 
int handle, w h, top, 
fullx, fully, fullw, fullh, 
char w, char h, box w, box h, 
wrkx, wrky, wrkw, wrkh; 

/* Message buffer. */ 
int msg_buf[8]; 

struct { 

char fnames[MAX] [15]; /* Char array for filenames. */ 
int count; /* Number of filenames read. */ 

} files; 

/* Window title. */ 

char *title = "C-manship"; 


main () 

{ 

appl_init (); /* 

open_vwork (); /* 

do_wndw(); /* 

v_clsvwk (handle); /* 

appl_exit (); /* 

} 


open vwork () 

{ 

int i; 

handle = graf_handle ( Schar^w, &char_h, &box w, &box h); 
for ( i=0; i<10; work in[i++] = 1 ); 
work in[10] = 2; 

v_opnvwk ( work in, Shandle, work-out ); 

} 


do_wndw () 

{ 

top = 0; 
get_fnames (); 


Initialize application. */ 
Set up workstation. */ 
Go do the window stuff. */ 
Close virtual workstation. */ 
Back to the desktop. */ 
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wind get ( 0, WF^WORKXYWH, Sfullx, Sfully, Sfullw, Sfullh ); 

w h = wind^create ( PARTS, fullx, fully, fullw, fullh ); 

wind set ( w h, WF NAME, title, 0, 0 ); 

wind_open ( w_h, 100, 20, 150, 151 ); 

calc_slid ( w_h, files.count, 14 ); 

graf mouse ( ARROW, 0L ); 

do { 

evnt mesag ( msg buf ); 

switch ( msg_buf[0] ) { /* msg_buf[0] is message type. */ 

case WM_SIZED: 

do_move (); 
break; 

case WM ARROWED: 

do_arrow (); 
break; 

case WM_VSLID: 

do_vslide (); 
break; 

case WM_REDRAW: 

do_redraw ( (GRECT *) &msg_buf[4] ); 
break; 

} 

} 

while ( msg buf[0] != WM_CLOSED ); 

wind^close ( w h ); 
wind delete ( w h ); 


do^arrow () 

{ 

switch ( msg_buf[4] ) { 

case WA_UPPAGE: 

do_uppage (); 
break; 

case WA DNPAGE: 

do^dnpage (); 
break; 

case WA_UPLINE: 

do_upline (); 
break; 

case WA_DNLINE: 

downline (); 
break; 

} 

} 


do_vslide () 

{ 
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GRECT r; 

int lines avail; 

wind get ( w h, WF WORKXYWH, &r.g x, &r.g y, &r.g_w, &r.g h ); 
lines avail = r.g h / char h; 

top = msg buf[4] * (files.count - lines avail) / 1000; 
wind set ( w h, WF VSLIDE, msg buf[4], 0, 0, 0 ); 
draw interior ( r ); 


do_uppage () 

{ 

GRECT r; 

int lines avail; 

wind get(w h, WF WORKXYWH, &r.g x, &r.g y, &r.g_w, &r.g h) ; 
lines avail = r.g h / char h; 
top -= lines avail; 
if ( top < 0 ) 
top = 0; 

draw interior ( r ); 


do^dnpage () 

{ 

GRECT r; 

int lines avail; 

wind get ( w h, WF WORKXYWH, &r.g x, &r.g y, &r.g w, &r.g h 

) ; 

lines_avail = r.g h / char h; 
top += lines avail; 

if ( top > files.count - lines avail ) 
top = files.count - lines avail; 
draw interior ( r ); 


do_upline () 

{ 

FDB s, d; 

GRECT r; 
int pxy[8]; 

if ( top != 0 ) { 

top -= 1; 

wind get(w h, WF WORKXYWH, &r.g x, &r.g y, &r.g w, &r.g h); 
set_clip ( TRUE, r ); 
graf mouse ( M_OFF, 0L ); 


s.fd addr 

= 0L; 



d.fd addr 

= 0L; 



pxy[0] = 

r.g_x; 



pxy[1] = 

r.g_y 

+ 

1; 

pxy[ 2 ] = 

r.g x 

+ 

r.g w ; 

pxy[3] = 

r • g_y 

+ 

r.g h - cha 

pxy[4] = 

r.g_x; 



pxy[5] = 

r.g_y 

+ 

char h + 1; 

pxy[6] = 

r.g x 

+ 

r.g w; 

pxy[7] = 

r • g_y 

+ 

\—1 

1 

1 

u 
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vro_cpyfm ( handle, S_ONLY, pxy, &s, &d ); 
v gtext ( handle, r.g x+char w, r.g y+char h, 
Sfiles.fnames[top][0] ); 

set_clip ( FALSE, r ); 
calc_slid ( w_h, files.count, 14 ); 
graf_mouse ( M_ON, 0L ); 

} 

} 

do_dnline () 

{ 

FDB s, d; 

GRECT r; 
int pxy[8]; 

int lines avail, index; 


} 


wind get ( w h, WF WORKXYWH, &r.g x, &r.g y, &r.g w, &r.g h 
lines avail = r.g h / char_h; 
if ( (top + lines avail) < files.count ) { 

top t= 1; 

index = top + lines avail - 1; 


set_clip ( TRUE, r 
graf_mouse ( M_OFF, 
s.fd_addr = 0L; 
d.fd addr = 0L; 


0L 


pxy[0] 
pxy[1] 
pxy[2] 
pxy[3] 
pxy 
pxy[5] 
pxy[6] 
pxy[7] 


4] = 


g_x; 

g y + char h 
g x + r.g w; 
g_y t r.g_h - 
g_x; 

t 1; 

+ r.g w; 


+ 1 ; 


1 ; 


g_y 
g_ x 
g 


_y + r.g h - char h - 1 ; 
vro_cpyfm ( handle, S_ONLY, pxy, &s, &d ); 

v gtext ( handle, r.g x+char w, r.g y+(lines_avail)*char h, 
Sfiles.fnames[index][0] ); 

if ( index != files.count-1 ) 

v_gtext ( handle, r.g x+char w, 
r.g_y+(lines_avail)*char_h+char h, 

&files.fnames[index+1][0] ); 

else 


v gtext ( handle, r.g x+char w, 
r.g y+(lines avail)*char_h+char h, 
" " ) ; 
set_clip ( FALSE, r ); 
calc_slid ( w_h, files.count, 14 ); 
graf_mouse ( M_ON, 0L ); 


get_fnames () 

{ 

char dta[44]; 

int end, p, x, null_found; 

p = 0; 

files.count = 0; 

Fsetdta ( dta ); 

end = Fsfirst ( 17 ); 
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while ( (end > -1) SS (files.count <= MAX) ) { 

null found = FALSE; 
files.count += 1; 
for ( x=0; x<14; ++x ) { 

if ( dta[30+x] == 0 ) 

null_found = TRUE; 
if ( null_found ) 

dta[30+x] = ' '; 

files.fnames[p][x] = dta[30+x]; 

} 

files.fnames[p][14] = 0; 

P += 1; 

end = Fsnext (); 

} 

} 


calc_slid ( w h, line_cnt, col_cnt ) 
int w h, line cnt, col cnt; 

{ 

int lines_avail, cols avail, vslid siz, pos; 

wind get ( w h, WF WORKXYWH, Swrkx, &wrky, Swrkw, &wrkh 

lines_avail = wrkh / char h; 

cols_avail = wrkw / char w; 

vslid_siz = 1000 * lines avail / line_cnt; 

wind set ( w h, WF_VSLSIZE, vslid_siz, 0, 0, 0 ); 

pos = (int) ( (float) (top) ) / 

( (float) (files.count - lines_avail) ) * 1000; 
wind set ( w h, WF_VSLIDE, pos, 0, 0, 0 ); 

} 


do^move() 

{ 

if ( msg_buf[6] < MIN_WIDTH ) 
msg_buf[6] = MIN_WIDTH; 
if ( msg_buf[7] < MIN_HEIGHT ) 
msgJouf[7] = MIN_HEIGHT; 
wind set ( msg buf[3], WF CURRXYWH, 

msg_buf[4], msg_buf[5], msg_buf[6], msg_buf[7] ); 
calc_slid ( w_h, files.count, 14 ); 

} 

draw interior ( clip ) 

GRECT clip; 

{ 

int pxy [4]; 

int x, lines avail, lines shown; 

graf mouse ( M_OFF, 0L ); 
set_clip ( TRUE, clip ); 

wind get(msg buf[3], WF WORKXYWH, Swrkx, Swrky, Swrkw, 
vsf interior ( handle, SOLID ); 


Swrkh); 
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vsf_color ( handle, WHITE ); 

pxy[0] = wrkx; 

pxy[l] = wrky; 

pxy[2] = wrkx + wrkw - 1; 

pxy[3] = wrky + wrkh - 1; 

vr_recfl ( handle, pxy ); 

lines avail = wrkh / char h; 
lines shown = files.count - top; 
if ( lines avail > lines shown ) { 

top = files.count - lines avail; 
if ( top < 0 ) 


for ( x=top; x<files.count; ++x ) 

v^gtext ( handle, wrkx+8, wrkyt(x+l-top)*char h, 
&files.fnames[x][0] ); 

set_clip ( FALSE, clip ); 
calc_slid ( w_h, files.count, 14 ); 
graf_mouse ( M_ON, OL ); 


do_redraw ( reel ) 
GRECT *recl; 

{ 


GRECT rec2; 

wind update ( BEG_UPDATE ); 
wind_get ( msg_buf[3], WF_FIRSTXYWH, 

&rec2.g_x, &rec2.g_y, &rec2.g_w, &rec2.g_h ); 

while ( rec2.g w && rec2.g h ) { 

if ( rc_intersect ( reel, &rec2 ) ) 

draw_interior ( rec2 ); 
wind get ( msg buf[3], WF NEXTXYWH, 

&rec2.g_x, &rec2.g_y, &rec2.g_w, &rec2.g_h ); 

} 

wind_update ( END_UPDATE ); 


set_clip ( flag, rec ) 
int flag; 

GRECT rec; 

{ 

int pxy[4]; 

pxy[0] = rec.gx; 

pxy[1] = rec.g_y; 

pxy[2] = rec.g x + rec.g w - 1; 

pxy[3] = rec.g_y + rec.g_h - 1; 

vs_clip ( handle, flag, pxy ); 

} 
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CHAPTER 21 - D.E.G.A.S. PICTURE VIEWER 

Everyone who's getting tired of studying GEM's windows please raise your hand. Yeah, that's what I 
thought. Okay, it's time to take up a new subject, something that, though it'll give you a lot of 
information on how your computer works, it won't give you a headache trying to understand it. 

One of the more useful things about the ST is the ability to have many screens of data in memory at 
once and flip between them as you like. I thought this would be a good subject to tackle since it 
enables us to see not only how we can accomplish "screen flipping" (which is really a simple process), 
but how to apply some of the other techniques we've learned, such as the programming of file 
selectors. We'll also take a look at some new information, such as the D.E.G.A.S. picture file format. 

We're going to load two D.E.G.A.S. format pictures into memory, and then use an alert box to choose 
which picture to view. We'll have to tell the program which files to load, so the first thing the 
program will do is bring up a file selector. Use it in the normal way to select two D.E.G.A.S. pictures 
for loading. 

While you're doing this, keep in mind that the program presented here is a stripped down model. In 
other words, it doesn't incorporate much in the way of error checking. In fact, it'll let you load just 
about any type of file into memory, whether it's D.E.G.A.S. or not. So do your own error checking, 
and make sure you're selecting the right type of file. 

If you click on the file selector's Cancel button for either picture, or if the program gets a file error, 
you'll be returned to the desktop. Once you get two files loaded, an alert box with three buttons will 
appear. Clicking on the first button will cause the first loaded picture to be displayed. Clicking on the 
second button will show the second picture. The Quit button should be used to leave the program 
and return to the desktop. Once a picture is displayed on the screen, clicking the left button will bring 
the alert box back, allowing you to make another choice or quit the program. 

Hey! That Space is Reserved! 

The first step in getting our picture files loaded into the computer is figuring out where we're going 
to store them. We need a lot of space — 32K for each picture — and we have to make sure that, 
wherever we store the picture information, it doesn't get in the way of our program or its data. Also, 
since we're going to be displaying a couple of different screens, we have to make sure we store the 
address of the original screen, as well as its color palette, so we can restore it when the program's 
finished. 

Take a look at the function init_screens() in Listing 1. The first thing we do here is store the desktop's 
color palette with the line: 

for (x=0; x<16; desk_palette[x++] = Setcolor(x,-1)); 

The function SetcolorQ is an XBIOS function and is defined in the OSBIND.H file. This function 
requires two integers as arguments. The first is the color you want to change (from 0 to 15), and the 
second is the color to change it to. 

Colors on the ST are formed by mixing the correct proportions of red, green, and blue, each of which 
can have a value from 0 (minimum) to 7 (maximum). The color value for blue is placed in the first 
nibble (four bits) of the integer; the value for green is placed in the second nibble; and the value for 
red is placed in the third. This works out well in hexadecimal: 0x007 is the brightest blue, 0x070 is the 
brightest green, and 0x700 is the brightest red. White is all the values at their maximum (0x777), 
while black is formed by setting all colors to the minimum (0x000). By combining the three basic 
colors in varying intensities, we can conjure up any of the ST's 512 possible colors. 
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But all that is beside the point (go ahead and boo; I deserve it). We don't want to change the colors 
(at least, not yet); we want to know what value they're currently set at, so we can store them for 
later retrieval. One thing I didn't tell you about the SetcolorQ function is that it always returns a 
color's previous setting (its color value before we changed it). If we make the second argument a 
negative number, it won't change the color register at all; it'll just return the color's setting. 

Now you can see how the above code segment works. We use a for loop to step through all 16 
possible elements of the color palette, calling SetcolorQ in each iteration with a color value of -1, in 
order to have the current color returned to us. Each of these colors is stored in the array 
desk_palette[], where they'll be when we're ready to restore the desktop's colors. Now that we've 
gotten that taken care of, we have to store the address of the desktop's screen (we do want to get 
back there eventually, you know). This line will do the job: 

scrn = PhysbaseO; 

Here, the variable scrn is a long integer that'll hold the address returned from PhysbaseQ. The 
function Physbase() returns the address of the physical screen, the area of memory currently 
displayed on your monitor. The function LogbaseQ returns the address of the logical screen, an area 
of memory where all output to the screen is to go. 

In most cases, the physical and logical screens are in the same location. For example, as I'm writing 
this article, I can see the new text I'm typing appearing on the screen. That means that the displayed 
screen and the one the program is sending text to are at the same address. Sometimes, though, we 
may find it handy to be able to direct screen data to a different place in memory, so we can update 
the screen "behind the user's back." Once the logical screen has been set up the way we want it, we 
can simply flip to it, creating the illusion of the screen being instantly updated. We'll see how all this 
works a little later. 

Now that we know where our physical screen is, we're ready to allocate some memory for a couple 
of logical screens. We can have only one physical screen, but we can have as many logical screens as 
you can store in memory. In the function init_screens(), we set up a while loop that first allocates a 
block of screen memory, then calls a function to read the picture data into it. To allocate a block of 
memory, we use the call: 

addr = Malloc(bytes); 

Here, the pointer addr will hold the address of the block of memory, and the long integer bytes is the 
number of bytes we wish to reserve. This function returns a 0 if the amount of memory we've 
requested is unavailable. One variation on the Malloc() call, making bytes equal to -1L, will return the 
total amount of memory available. 

You've probably noticed, though, that our call to MallocQ in Listing 1 looks quite a bit more complex: 

pic[x] = (Malloc(32768L) & OxffffffOO ) + 0x0100; 

Am I just trying to show off? No; not at all. 

First, even though pic[x] doesn't look like a pointer, it is. In fact, pic[] is an array of pointers (actually, 
long integers, but for our use that amounts to the same thing). For programming purposes, it's very 
convenient to store the addresses of our screens in an array, so that we can get at them easily with 
some sort of loop. 

Next comes that strange looking Malloc() call. It looks strange to you because there's one little detail 
I've yet to mention, the fact that the ST's screen memory must always start on a 256-byte boundary. 
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And, since Malloc() doesn't know or care about this little requirement, it's up to us to smooth things 
over. 

The first step in getting to a safe 256-byte boundary is to use C's AND operator to mask off the eight 
right-most bits of the address, using the hex value OxFFFFFFOO as our mask. This value has every bit 
set except the right-most eight. The AND operator compares the bits of two values, returning a true 
(1) when both bits are on and a false (0) when either or both the bits are off. What that means for us 
is that every bit we have off in the mask will result in a 0 in the bit it's being ANDed with. Let's say the 
address returned from Malloc() was 0x034CC3E2. After ANDing it with our mask, we'd have 
0x034CC300, which is an address on a 256-byte boundary. 

But even though we're now on the boundary we wanted, it's not a safe boundary. Why? Because the 
address we have now is lower than the one returned from Malloc(). That means we're no longer in 
the area we just reserved; we're actually before it. If we try to load data there, we'll probably end up 
clomping all over our program — and getting a delightful string of bombs up on the screen. 

That's why, after completing the AND operation, we add 0x00000100 (256 decimal) to the resultant 
address. That pushes it back into our reserved area. 

"Ah!" you cry, in that smug manner you use when you think you've caught the professor with his foot 
in it. "If we're pushing the address forward, doesn't that mean that, when we load our picture data, 
the last few bytes will be placed outside the reserved area, beyond the other end?" 

Nope. You see, we've reserved 32,768 bytes (that's a full 32K), and we really need only 32,000 bytes 
for our picture data. When people tell you that screen memory on the ST is 32K, they're not telling 
you the whole truth. It's actually a bit short of a full 32K. We just like to round it off when we speak. 
(You ever hear people refer to the SF314 disk drive as a one meg drive, even though you can only 
store 720,000 bytes on the disk? Same idea.) 

One thing we do have to watch out for, though, is how we handle any subsequent calls to MallocQ, 
because it doesn't know we've finagled the address it gave us the first time around. The next time we 
allocate some memory, we have to remember to add the same amount to the returned address, or 
we're sure to make digital footprints in the previous areas. And digital footprints often result in the 
Big Kablooey. (In our case, since we're using those areas only for a screen display, we'd simply end up 
with some funny looking pictures.) 

Okay, we've got the memory we need to store our pictures. Now let's think about how we're going to 
load them. The first step is to get the picture's filename, and the obvious way to do that is with 
GEM's handy file selector box. Included in Listing 1 is a function called select_file(). This is a generic 
file-selector routine that I came up with that you can use in your own programs. It handles some of 
the minor details for you, allowing you to just call a file selector and have the complete filename 
(including the path) returned to you. (You're welcome.) 

If you look at the function get_pic(), you'll see how we get started. First, because it's required by 
select_file(), we have to come up with a default filename. This will appear tacked on to the end of the 
pathname field in the file selector and allows us to narrow the number of files shown when the box 
first comes up. In our example, we start with the string "* .PI" then finish the default name by adding 
the proper D.E.G.A.S. resolution indicator. Adding the ASCII value of "1" to the value returned from 
GetrezQ performs that trick. 

Our file selector function, select_file(), returns the complete chosen filename and the button that 
was clicked to exit the file selector. The call to the function looks like this: 

select_file(path,file,default,flag); 

Here, path is a pointer to a 64-byte character array and is where the function will store the 
completed filename. The pointer file is the address of a 13-byte character array that'll hold the 
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selected filename after the call to fsel_input(). We may also, before the function call, store a 
filename here that we want to appear in the filename field of the file selector box. The pointer 
default contains the address of a string containing the text we want added to the selector's 
pathname field. And finally, flag is a Boolean value that tells the function whether we want the string 
pointed to by file to appear in the file selector's file field. 

It sounds complicated at first, but I've found that using this function is a lot easier than trying to 
remember how to handle the file selector each time I need it. 

As I mentioned before, select_file() returns the value of the file selector button that was clicked. 
Strangely enough (or perhaps it was done purposely), these values also correspond to obvious 
Boolean values: the Cancel button returns 0, and the OK button returns 1. In the function get_pic(), 
we use this returned value as a Boolean to evaluate an if statement. In other words, if the user clicks 
on the file selector's Cancel button for either of the two files we're going to be loading, we'll know 
not to read the file and, instead, exit the program. 

If the user clicks the file selector's OK button, we call the function read_degas() to attempt to load 
the file chosen. If the file loads all right, this function will return a value of TRUE. If an error is 
encountered (maybe the file doesn't exist), it returns a value of FALSE. We use this returned value in 
another if statement to determine whether we should continue or return to the desktop. In a full- 
scale application program, you would want to give the user a message if you ran into an error, but for 
the sake of brevity, we've kept things to a minimum in the example program. 

Let's turn our attention now to read_degas(). It's here that we actually read the selected picture file 
into memory. This function needs to know which picture we're loading and the complete filename. 
The first thing we must do is open the file, but we have to make sure we open it to "read binary." We 
covered the open() function previously, but we didn't talk about the 0_BINARY flag. When we open 
the file with this flag (it's defined at the top of the listing as 8192), we're telling the system that we 
want the file read from the disk in an untranslated form, as a continuous block of data, rather than a 
series of lines ending with carriage returns and line feeds. 

Before we go any further, we need to discuss the format in which D.E.G.A.S. (the unsqueezed variety) 
pictures are saved to disk. If you've ever looked at a disk directory containing these picture files, 
you've undoubtedly noticed that they are 32,034 bytes. In order to get the picture up on the screen 
properly, we have to know what each of these bytes are. 

The first two bytes of a D.E.G.A.S. file indicate the picture's resolution. It's interpreted as a word 
value: 0x0000, 0x0001, or 0x0002, for low, medium or high resolution, respectively. Normally, we'd 
want to check the resolution of the picture against the computer's current resolution, to make sure 
they match, and if they don't, give the user an error message. But, as I said before, for the sake of 
brevity, we're going to do things quick and sloppy and just throw away those two bytes after we've 
read them. 

The next 32 bytes (16 words) are the picture's color palette. That we don't want to throw away; we 
want to read it into the array we've set up for storing this information. 

Finally, the last 32,000 bytes are the actual picture data. We read that information into the area of 
memory starting at the address stored in the appropriate element of the pic[] array. 

Now that we've got all the data read, we close the file and return a value of TRUE to the calling 
function. Notice that, in the function read_degas(), we're using the value returned from the open() 
function in an if statement. Doing this guarantees, in the case of a file error, that we skip over all the 
subsequent file handling code, and just return from the function a value of FALSE. 

Once we get two picture files loaded okay, program execution is turned over to the function 
flip_screens(), where we get a chance to actually view the pictures. We begin by calling up an alert 
box with three buttons, one button for each picture plus a Quit button. We use the value returned 
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from the alert box as an index into the pic[] array, where the pointers to the screens are stored. To 
flip between the different screens, we use the call: 

Setscreen(log,phys,res); 

Here, log is the address of the logical screen, phys is the address of the physical screen, and res is the 
screen resolution we want to switch to. If we don't want to switch screen resolutions, we just give 
res a negative value. In fact, all parameters with a negative value will be ignored. 

In most cases, you would set both the logical and physical screen to the same address. As for the 
resolution, you'll almost always want to leave it unchanged (use a negative value) because GEM is 
never informed of resolution changes, and that can lead to nasty complications. 

After flipping the screen, we wait for a mouse button click using a call to evnt_button(), after which 
we bring up the alert box to get another choice. We keep displaying the selected picture until the 
Quit button is clicked, after which we close things up and return to the desktop. 

Putting It Back Where We Found It 

But we can't just go blithely on our way, returning to the desktop by just closing the virtual 
workstation and calling appl_exit(). Nosiree. We've got cleaning up to do. We've allocated a bunch of 
memory for our picture files, and before we leave, we have to give it back. Not a tough thing to do. 
The following call will return a block of memory (one that was allocated with Malloc()) to the system: 

Mfree(adr); 

The pointer adr is the address of the block we want to de-allocate. You need to make a separate call 
to Mfree() for each block allocated, and you must return the blocks in the reverse order you 
allocated them. 

Once we've returned all the memory to the system, we can exit the program in the usual manner. 
You can see all this being done in Listing 1 in the function clean_up(). 

Mission Complete 

Now that you know how all this screen flipping stuff works, why don't you modify the program so 
that you can load more than two D.E.G.A.S. pictures? Use the mouse to flip through them. When you 
get to the last of the pictures, use an alert box to ask the user whether he wants to see the pictures 
again or quit. Practice makes perfect! 


Program Listing #1 

j*********************************************** I 

/* C-manship, Listing 1 */ 

/* CHAPTER 21 */ 

/* Developed with Megamax C */ 

/***********************************************J 

#include <osbind.h> 

#define TRUE 1 

#define FALSE 0 

#define 0_BINARY 8192 

#define QUIT 3 

#define LEFT_BUTTON 1 

#define DOWN 1 
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/* The usual required GEM global arrays */ 

int work in[11], 

work_out[57], 

pxyarray[10], 

contrl [ 12] , 

intin[128], 

ptsin [12 8] , 

intout [12 8] , 

ptsout[12 8] ; 

/* Global variables */ 
int handle, dum; 

long pic[2], /* Pointers to logical screens. */ 

scrn; /* Pointer to physical screen. */ 

int desk_palette[16]; /* Desktop color palette. */ 
int pic_palette[2][16]; /* Picture color palettes. */ 


main () 

{ 

appl_init (); 
open vwork (); 
do_pictures (); 
clean_up (); 
appl_exit (); 

} 


open vwork () 

{ 

int i; 

/* Get graphics handle, initialize the GEM arrays and open */ 
/* a virtual workstation. */ 

handle = graf handle ( &dum, &dum, &dum, &dum); 
for ( i=0; i<10; work in[i++] = 1 ); 
work in[10] = 2; 

v_opnvwk ( work in, &handle, work-out ); 

} 


/* Initialize application. */ 
/* Set up workstation. */ 
/* Go do the picture stuff. */ 
/* Get everything back to normal. */ 
/* Back to the desktop. */ 


do_pictures () 

{ 

/* If the pictures are loaded okay, */ 
/* then allow user to view them. */ 


} 


if ( init_screens () ) 

flip_screens (); 


init_screens () 

{ 

int x, /* Index variable. */ 

okay; /* File load flag. */ 

/* Store the desktop's color palette. */ 


Port: HYPertext by Lonny Pursell & PDF by DrCoolZic (jig) - VI.0 Oct. 2010 


Page 204/321 


C-MANSHIP COMPLETE - by CLAYTON WALNUT 


for ( x=0; x<16; desk_palette[x++]=Setcolor (x, -1) ); 

/* Store the address of the desktop's screen. */ 
scrn = Physbase (); 

/* Reserve memory for pictures and load them */ 

/* into the allotted space, storing pointers */ 

/* to them in the pic[] array. */ 

okay = TRUE; 
x = 0 ; 

while ( (okay == TRUE) && (x < 2) ) { 

pic[x] = ( Malloc (32768L) & OxffffffOO ) + 0x0100; 
okay = get_pic ( x++ ); 

} 

return ( okay ); 


flip_screens () 

{ 

int choice; /* Button number clicked in alert box. */ 
choice = 1; 

/* View pictures until QUIT button is clicked. */ 
while ( choice != QUIT ) { 

/* Call up alert box to get user's picture choice. */ 
choice = form^alert ( 0, "[2][Choose picture to \ 

view][One|Two|Quit]" ); 

/* We only want to show a picture if the */ 

/* QUIT button hasn't been clicked. */ 

if ( choice != QUIT ) { 

/* Set the screen to show the chosen picture. */ 
Setscreen ( pic[choice-1], pic[choice-1], -1 ); 

/* Set the palette to the picture's settings. */ 
Setpalette ( &pic_palette[choice-1][0] ); 

/* Wait for a button click. */ 

evnt button(1,LEFT BUTTON,DOWN,&dum,&dum,&dum,&dum); 


get_pic ( num ) 

int num; /* Number of picture to load. */ 

{ 

char path[64], /* Storage for picture's pathname. */ 

file[13], /* Storage for picture's filename. */ 

pictype[6]; /* Storage for default picture filename. */ 

/* Build default picture filename. */ 
strcpy ( pictype, "*.PI " ); 
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pictype[4] = Getrez () + '1' ; 

/* If file selector CANCEL button wasn't clicked, */ 
/* read the chosen DEGAS file into memory. If an */ 
/* error is returned, the program will abort. */ 

if ( select_file ( path, file, pictype, FALSE ) ) 

if ( read_degas ( num, path ) ) 

return ( TRUE ); 

else 

return ( FALSE ); 

else 

return ( FALSE ); 


read degas ( num, pathname ) 

int num; /* Picture number to read. */ 

char *pathname; /* Picture's pathname. */ 

{ 

int f h, /* File handle. */ 

buf[10]; /* Temp buffer for unused bytes. */ 

/* Process file only if no error is returned when opening. */ 
if ( (f h = open ( pathname, 0 BINARY )) != -1 ) { 

/* First two bytes is resolution data. */ 
read ( f_h, buf, 2 ); 

/* Next 32 bytes (16 words) is the color palette. */ 
read ( f_h, &pic_palette[num][0], 32 ); 

/* Finally, we have 32K of picture data. */ 
read ( f_h, pic[num], 32000 ); 

/* Close file and tell calling function */ 

/* that everything went all right. */ 

close ( f_h ); 
return ( TRUE ); 

} 

/* In case of error opening the file. */ 
else 

return ( FALSE ); 

} 
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select_file ( path, fnme, deflt, display) 

char *path, /* Address for path storage. */ 

*fnme, /* Address for filename storage. */ 

*deflt; /* Address of default filename. */ 

int display; /* Display default filename? */ 

{ 

int x, /* Loop variable. */ 

choice, /* Button clicked from file selector box. */ 
len; /* String length. */ 

char ch; /* Temp character storage. */ 

/* Clear filename string if not to be displayed. */ 
if ( display == FALSE ) 

for ( x=0; x<13; fnme[x++] = '\0' ); 

/* Build file selector box pathname. */ 

Dgetpath ( path, 0 ); 
len = strlen ( path ); 
path[len] = ' ; 

strcpy ( &path[ len + 1 ], deflt ); 

/* Call up file selector box to get user's choice. */ 
fsel_input ( path, fnme, Schoice ); 

/* Find last significant character in pathname in */ 

/* order to delete the filename portion of the path. */ 

len = strlen ( path ); 
x = len-1; 

while ( path[x] != '\\' && path[x] != && x > 0 ) 

--x; 

strcpy ( &path[x+l], fnme ); 
return ( choice ); 


clean_up () 

{ 

/* Setscreen back to desktop. */ 

Setscreen ( scrn, scrn, -1 ); 

/* Restore original color palette. */ 

Setpalette ( desk_palette ); 

/* Return the reserved memory back to the system. */ 
Mfree ( pic[1] ); 

Mfree ( pic[0] ); 

/* Close virtual workstation. */ 
v_clsvwk (); 

} 
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CHAPTER 22 - THE INTERNAL CLOCK/CALENDAR 


This time around we'll tackle a subject we've managed to avoid so far — the Atari ST's real-time clock. 
Actually, "avoid" probably isn't a good word to use here, since reading and setting the ST's clock is 
really not very hard. You just need to become proficient with handling data in a bitwise fashion 
rather than as words or bytes. And as we'll soon see, attaining those skills will not require an 
inordinate amount of effort, and those same skills will be a valuable addition to your future C 
programming projects. 

But first you should get this chapter's sample program up and running, and that involves a little more 
work than usual. You're going to need to create the dialog box shown in Figure 1. There's two ways 
you can do this. The first is to type in Listing 3 with ST BASIC (make sure you check your typing with 
ST Check, see Appendix A), and then run it. The program will create the necessary resource file for 
you. 



Figure 1 

The other way to produce the dialog box is to use a resource construction program. The dialog 
contains only four objects, but they must be created and named carefully. The objects are the 
editable text fields that show the time and date and the two exit buttons. If you want to create your 
own dialog box, here is the information you need to know: 

The dialog box itself is named DATEDIAL. The OK button is named OKBUTN and is simply a shadowed, 
exit button. The CANCEL button is named CANBUTN and is a shadowed, exit button, but it is also set 
as the default. The "Time" field is an unboxed, editable text string that is named TIMEFLD. Its ptmplt, 
pvalid, and ptext strings, shown in order, are: 

Time: : : 

999999AA 

000000AM 

The "Date" field is also an unboxed, editable text field. It's named DATEFLD, and its ptmplt, pvalid, 
and ptext strings, also in their respective order, are: 

Date: / / 

999999 

000000 

That's all you need to know to reproduce the dialog box shown in Figure 1 (except that you must 
name the RSC file DATE.RSC). If all of this sounds confusing, then either review Chapters 14 and 15, 
which cover dialog boxes, or use Listing 3 to create your resource file. 

Now that you've created your resource file, you may type in Listing 1 and compile it. If you used the 
ST BASIC program to create your resource file, you must also type in Listing 2, before you try to 
compile the program, and save it to disk as DATE.H. 
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Now run the program. If you've got the resource file in the same directory as the program, you'll see 
the dialog box shown in Figure 1. (If you're missing your resource file, the program will warn you, and 
then return to the Desktop.) The time and date shown in the dialog box are the current settings of 
your system clock. If you'd like to reset the clock, just edit the time and date strings and click on the 
OK button. If the strings you've entered are valid, the program will reset your system's clock and 
return to the Desktop. Otherwise you'll receive an error alert box, and you'll have to reenter the 
information. If you're satisfied with the time as it is, click on the CANCEL button or simply press 
Return. 

Computer Dating 

Let's take a look at Listing 2 and see what's going on here. Most of what's being done in the program 
you should already be familiar with. For instance, we long ago discussed how to load a resource file 
and get a dialog box up on the screen. In case you've gotten a little rusty, the program listing is 
commented enough so that you can easily see what's being done. 

Take a look at the function get_date(). It's here that we retrieve the system date from the computer's 
clock and convert it into a form that we can use in our dialog box. First we get the date with the call 

date = TgetdateO; 

where date is an integer. The function TgetdateQ is defined in your OSBIND.H file as gemdos(0x2a) 
and returns all the information we need to figure out the current date. Piece of cake, right? Not 
quite. If your noodle is active today, you'll remember that our dialog box displays the date by month, 
day, and year. However, the TgetdateQ call returned only one value. See a problem here? 

In order to simplify the process of storing and passing the system date, the people who designed 
your ST's OS decided to cram all the information we need to extract the current month, day, and year 
into a single integer; and if you're really on the ball today, you'll realize that that means we're going 
to have to finagle some bits in order to separate the information we want from the information we 
don't care about. 

The system date returned from the TgetdateQ function is formatted in the following manner: Bits 0 
to 4 (counting from right to left, remember) contain the day, bits 5 to 8 contain the month, and bits 9 
to 15 contain the year since 1980, or, in other words, the current year minus 80. Figure 2 illustrates 
this format. What we have to do is figure out a way to extract the day, month, and year from the 
entire integer. Thank heavens for bitwise operations! 


Year 

Month 

Day 

0 

0 

0 

1 

0 

0 

0 

1 

0 

1 

1 

1 

0 

1 

0 

1 


Hour 

Minutes 

Seconds 

0 

1 

1 

1 

1 

1 

0 

1 

1 

0 

0 

1 

1 

0 

1 

1 


FIGURE 2 


A Bit About Bits 

The C programming language supplies us with five operators that can manipulate the bits that make 
up a piece of data. Some of them you've seen before; a couple of them are new to you. Those 
operators are: 
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& Bitwise AND 

A Bitwise exclusive OR 

| Bitwise inclusive OR 

« Left shift 

» Right shift 

We've already had experience with the bitwise AND and bitwise inclusive OR operators. The AND 
operator compares the bits of two values and places into the result a 1 in any position where both 
bits of the compared values are set and a 0 in every other case. This allows us to "mask" out the bits 
in a value that we're not interested in. We create a mask by setting the bits of the mask that 
correspond to the information we wish to extract from the value of interest. Every other bit is turned 
off. 

Let's say we wanted to get the value of the low byte of a word. We would create a mask that looked 
like this: 0000000011111111. Suppose the value from which we want to extract information is called 
number and the binary representation of number is 0010110101100110. The calculation would look 
like this: 


0010110101100110 

<-- 

number 

0000000011111111 

<-- 

Mask 

0000000001100110 

<-- 

Result 


As you can see, the result contains only the bit values we wanted to retain. In a C program the above 
calculation would be written as follows: 

result=number&0x00ff 

The inclusive OR operator is almost the opposite of the AND operator. Rather than extracting 
portions of a value, it lets us insert them. When you inclusive OR two values together, the result will 
have a bit set wherever there was a bit set in either one or both of the compared values. Let's say we 
wanted to merge the values contained in two variables called varl and var2. The binary 
representation of varl is 0000000010101011, and the binary representation of var2 is 
1101101100000000. The inclusive OR operation looks like this: 


0000000010101011 

<-- 

numl 

1101101100000000 

<-- 

num2 

1101101110101011 

<-- 

result 


You can see from the result that we've combined the low byte of numl with the high byte of num2. 
There's one important thing you must be aware of, though. This combining of values will work only 
when the positions that will hold the merged value all contain zeroes. In other words, we would not 
get the proper result in the above operation if the high byte of numl was not cleared: 


1111111110101011 

<-- 

numl 

1101101100000000 

<-- 

num2 

1111111110101011 

<-- 

result 


The same problem would crop up if the low byte of num2 hadn't been cleared. 

A bitwise exclusive OR is similar except that the result will contain a 1 only in those positions where 
either one or the other bit is set. If both bits are set or both bits are cleared, the result will be a 0. 
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The left shift operator causes the bits in the first operand to be shifted to the left the number of 
times found in the second operand. The right-hand, emptied bits will be filled with zeroes. For 
instance, let's take a variable named num that contains the binary value 1011010110101101. If we 
were to perform the operation num«5, the result would be 1011010110100000. 

The right shift operator works much the same way, except that the emptied left-hand bits may or 
may not be zero-filled, depending on the machine and data type you're using. The rule is if the data 
type is unsigned, you are guaranteed to get a zero fill; otherwise, the left-hand bits may be filled with 
the value of the sign bit (the most significant bit). 

But What About the Date? 

So here we are, finally back to the original problem of extracting the day, month, and year from the 
single integer returned by the TgetdateQ call. Think about it for a minute. Have you got it figured out 
yet? No? 

Let me explain, then. The information we need to get the day is contained in bits 0 through 4, right? 
So, what we need to do is mask out bits 5 through 15. Then our result will contain only the value 
stored in the lower five bits -- and that value is current day. (Of course, whether this value matches 
your calendar or not depends on whether your system clock has been set properly.) Let's say the 
value returned from TgetdateQ is the one shown in Figure 2. Figure 3a then illustrates the operation 
involved in extracting the day. 

0001000101110101 
& OxOOlf 

0000000000010101 21 

FIGURE 3a 


First, we create a mask to AND with our integer, a mask that will clear bits 5 through 15, while at the 
same time maintain the values of the lower five bits. The proper mask is 0000000000011111 in 
binary or OxOOlf in hexadecimal. (Note that it's much easier to create your mask in binary first then 
convert it to hexadecimal. That way you can easily see which bits you're setting.) Then all we have to 
do is AND the system date with our mask. In Listing 1, the line that does this is: 

day = date & OxOOlf; 

Say! That was pretty easy, wasn't it? The next step is to get the month, but we run into a little 
complication with that one. If we were to just AND out the bits we weren't interested in, we'd end up 
with the value 0000000101100000 which translates to a decimal value of 352! Ouch! Aren't there 
only 12 months? To get the value we really want, we have to move the four bits we're interested in 
to the right five places. Sounds to me like a good job for the right shift operator. 

But let's perform the shifting first and then mask out the unnecessary bits. That way we're sure we 
get no garbage in the upper bits as a result of the shift operation. Theoretically, it would work either 
way, since our sign bit will be a zero. But I learned a long time ago that, when it comes to computers, 
you can only trust what you know. And I know that if I do the AND operation last, I'll have the result 
I'm looking for. In Listing 1, the line that gets us our month looks like this: 

mnth = (date >> 5) & OxOOOf; 

This operation is illustrated in Figure 3b. 
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0001000101110101 

»5 

0000000010001011 
& OxOOOf 

0000000000001011 11 

FIGURE 3b 

Finally, to get the year, we have to perform the same operation, only we'll be shifting the bits down 
nine places instead of five, and we'll be using a different mask because we're interested in a different 
number of bits. Figure 3c illustrates this operation, and the equivalent line in Listing 1 looks like this: 

year = ((date >> 9) & 0x007f) + 80; 


0001000101110101 

»9 

0000000000001000 
& 0x007f 

0000000000001000 8 

FIGURE 3c 


Although Figure 3c doesn't show it, we have to remember to add 80 to the result because, as I 
mentioned before, the year returned from the TgetdateQ call is the year since 1980. 

Some Timely Information 

Now let's look at the function get_time() in Listing 1. We get the system time with the call 

time = TgettimeO; 

where time is an integer. Bits 0 through 4 of this value will contain the seconds divided by two, bits 5 
through 10 will contain the minutes, and bits 11 through 15 will contain the hour. We can extract this 
information in the same way we calculated the date -- by shifting the bits in which we're interested 
all the way to the right, and then using a mask and the AND operation to clear the bits in which we're 
not interested. 

I don't think we need to go into a lot of detail here, but there is one thing I want to mention -- 
something that we didn't have to deal with when we calculated the date. The value for the hour 
portion of the system time is in 24-hour format; that is, it'll be a value from 0 to 23. Values from 0 to 

II represent the hours of midnight to 11 a.m., and the values from 12 to 23 represent the hours 
from noon to 11 p.m. In order to make the time more readable, our function get_time() does some 
converting so that the time will be displayed in the manner we're most used to seeing it. (Of course, 
if you're in the military, you may not approve of this conversion!) 

Also, keep in mind that the value for the seconds is the number of seconds divided by two. This 
means that you must multiply times two the value for the seconds that was returned by the 
Tgettime() function. This also means that your ST's clock is only accurate to the nearest even second. 

Setting the Time and Date 

Setting the system's time and date requires only that we reverse the process we used to get the time 
and date. Instead of using an AND operation, we'll be using the inclusive OR, and instead of shifting 
bits to the right, we'll be shifting them to the left. 
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In Listing 1, the function set_date() handles both the setting of the time and the setting of the date. 
To set the time, we use this call: 

Tsettime( time ); 

where the integer time uses the same bit format we studied when we discussed the Tgettime() call. 
To set the date, we use this call: 

Tsetdate( date ); 

where the integer date used the same bit format we learned about when we discussed the 
Tgetdate() call. These functions are defined in your OSBIND.H file. Let's take just a quick look at how 
we prepare the integers for these calls. Let's use time as our example this time around. Suppose the 
time we wanted to set the system clock to was 14:36:34 (that's 2:36 p.m. for those of you who could 
never get the hang of a 24-hour clock). Setting the seconds is easy: 

time = seconds; 

Here, seconds is equal to 17. (Remember that the number of seconds must be divided by two; that's 
the only way the designers of the OS could get the time to fit into an integer.) 

Now time contains the binary value 0000000000010001, which equals 17 in decimal. Our value for 
minutes is 36, which is 0000000000100100 in binary. We have to move this information up into bits 5 
through 10. The operation minutes=minutes«5 gives us a result of 0000010010000000 which is 
exactly what we want. 

Now we have to combine the seconds (the value of which is already stored in time) with the minutes. 
The operation time=time | minutes does the trick handily. On a binary level that operation looks like 
this: 


0000000000010001 <-- time (seconds) 
0000010010000000 <-- minutes 


0000010010010001 <-- time (seconds and minutes) 

To add the hours, we do the same sort of operation, only we'll be shifting the value for hours 11 
places to the left. I might also add that it doesn't matter in what order we store the seconds, minutes 
and hours, as long as we follow the general procedure outlined above. If you look at Listing 1, you'll 
see that I started with the hours instead of the seconds. 

All Ashore Who's Going Ashore 

That about covers it. As you peruse this chapter's program, you may come across a couple of 
functions that aren't familiar to you. If so, just look them up in your manual. There's nothing 
complicated with any of them, and you should be easily able to figure out how everything in the 
sample program works. 
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Program Listing #1 

j •kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk J 

/*C-manship, Listing 1*/ 

/* CHAPTER 22 */ 

/*Developed with Megamax C*/ 

J •k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k'k-k J 

#include <osbind.h> 

#include <gemdefs.h> 

#include <obdefs.h> 

#include "date.h" 

#define TRUE 1 
#define FALSE0 
#define MATCHO 

/* GEM arrays */ 
int work in [ 11], 
work_out[57], 
contrl [ 12] , 
intin[128], 
ptsin [12 8] , 
intout [12 8] , 
ptsout[128]; 

int handle,/* Application handle. */ 
dum; /* Dummy storage.*/ 

char *get_tedinfo_str (); 


jkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* Main program. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

main () 

{ 

appl_init (); /* Init application. */ 

open vwork ();/* Open virtual workstation. */ 

do_date (); /* Go do our thing.*/ 

rsrc^free (); /* Release resource memory.*/ 

v_clsvwk ( handle );/* Close virtual workstation.*/ 

appl_exit (); /* Back to the desktop.*/ 

} 


/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* do_date () 

* Loads the resource file and handles the dialog box. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkj 

do_date () 

{ 

int dial x, /* Dialog's X coord.*/ 

dial_y, /* Dialog's Y coord.*/ 
dial_w, /* Dialog's width.*/ 
dial_h, /* Dialog's height. */ 

choice, /* Exit button clicked from dialog. */ 
okay; /* Flag indicating if entered date valid. */ 

OBJECT *datedial addr; /* Address of dialog box. */ 

char date_str[8], /* String to hold date. */ 
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time_str[10]; /* String to hold time. */ 

char *string; /* Temp string pointer. */ 

graf mouse ( ARROW, 0L ); 

/* Load resource file. */ 

if ( Irsrc^load ( "\date.rsc" ) ) 

form^alert ( 1, "[1][date.rsc missing!][OK]" ); 


else { 


/* Get address of dialog and init time and date strings. */ 
rsrc_gaddr ( R TREE, DATEDIAL, &datedial_addr ); 
get_time ( time_str ); 
get_date ( date_str ); 

/* Copy system time and date into dialog box, */ 
string = get_tedinfo_str ( datedial_addr, TIMEFLD ); 
strcpy ( string, time_str ); 

string = get tedinfo str ( datedial^addr, DATEFLD ); 
strcpy ( string, date_str ); 

/* Prepare dialog box for drawing, and init flag. */ 
form^center(datedial_addr,&dial x,&dial_y,&dial_w,&dial h); 
form dial(FMD_START,0,0,10,10,dial_x,dial y,dial_w,dial h); 
okay = TRUE; 

/* This loop repeats until the user clicks CANCEL */ 

/* or until the user enters a valid date and clicks OK. */ 
do { 

/* Draw dialog and allow user to manipulate it. */ 

obj c^draw(datedial_addr,0,8,dial_x,dial_y,dial_w,dial_h); 

choice = form do ( datedial_addr, TIMEFLD ); 

/* Reset the state of the chosen button. */ 
datedial addr[choice].ob_state = SHADOWED; 

/* If OK clicked, check entered date and set system */ 

/* date if date entered is valid, */ 
if ( choice == OKBUTN ) { 

okay = chk_date ( datedial_addr ); 
if ( okay ) 

set_date ( datedial_addr ); 

} 

} 

while ( okay == FALSE && choice == OKBUTN ); 

/* Get rid of the dialog box. */ 

form_jdial(FMD^FINISH,0,0,10,10,dial_x,dial y,dial_w,dial^h); 

} 

} 


j ■k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k-k'k-k'k-k'k-k-k'k'k-k'k-k'k-k-k'k-k'k 

* chk_date () 

* Examines the strings in dialog for a valid date 

* and valid time. 

■ k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k-k'kJ 

chk^date ( dial_addr ) 

OBJECT *dial_addr; /* Address of dialog box. */ 
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{ 

int mnth, day, year, /* Date and time broken into integers.*/ 
hour, min, sec, 

space, /* Flag for bad chars in time string.*/ 
okay,/* Flag indicating valid time & date. */ 
x; /* Loop variable. */ 

char m[3], d[3], y[3], /* Date & time as character arrays. */ 
h[3], mn[3], s[3], 
ap[3]; /* "AM" or "PM" */ 

char *date_str, /* Pointer to string containing date. */ 

*time str; /* Pointer to string containing time. */ 

/* Init date and time integers to error condition. */ 
mnth = day = year = hour = min = sec = -1; 

/* Get address of string containing date. */ 
date_str = get_tedinfo_str ( dial addr, DATEFLD ); 

/* Convert date string to integer format. */ 
if ( strlen ( date_str ) == 6 ) { 

strncpy ( m, date^str, 2 ); 
m [ 2 ] = 0 ; 

strncpy ( d, &date_str[2], 2 ); 

d[2] = 0; 

strncpy ( y, &date_str[4], 2 ); 

y[2] = 0; 

mnth = atoi ( m ); 
day = atoi ( d ); 
year = atoi ( y ); 

} 

/* Get address of string containing time. */ 
time_str = get tedinfo_str ( dial addr, TIMEFLD ); 

/* Check for spaces in time string. */ 

space = FALSE; 

for ( x=0; x<6; ++x ) 

if ( time_str[x] == ' ' ) 

space = TRUE; 

/* Convert time string to integer format. */ 
if ( (strlen ( time_str ) == 8) && (space ) { 

strncpy ( h, time_str, 2 ); 

h[2] = 0; 

strncpy ( mn, &time_str[2], 2 ); 
mn [ 2 ] = 0; 

strncpy ( s, &time_str[4], 2 ); 

s[2] = 0; 

hour = atoi ( h ); 

min = atoi ( mn ); 

sec = atoi ( s ); 

strcpy ( ap, &time_str[6] ); 

} 

/* Examine time and date for validity. */ 
if ( mnth < 1 | mnth >12 | day < 1 | day > 31 

I year < 0 | year > 99 | hour < 0 | hour > 23 | min < 0 
| min > 59 | sec < 0 | sec > 59 | 

((strcmp(ap, "AM" )!=MATCH) && (strcmp(ap, "PM" )!=MATCH))) { 
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okay = FALSE; 

form alert ( 1, "[1][Date or time not valid!][CONTINUE]" 

) ; 

} 

else 

okay = TRUE; 
return ( okay ); 

} 


/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* set_date () 

* Sets the system time and date to the values 

* entered into the dialog box. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkJ 

set_date ( dial_addr ) 

OBJECT *dial_addr; /* Address of dialog box. */ 

{ 

char *string; /* Temporary string pointer. */ 
char s[3];/* Temporary string storage. */ 
int h,/* Work variable.*/ 

time, /* Time in system format.*/ 
date; /* Date in system format.*/ 

/* Get address of string containing time. */ 
string = get tedinfo_str ( dial addr, TIMEFLD ); 

/* Extract "hours" portion and convert to integer. */ 
strncpy ( s, string, 2 ); 
h = atoi ( s ); 

/* Adjust hour to the 24-hour clock format. */ 


if ( 

\ (strcmp ( 
h += 12; 

&string[6], "PM" ) 

== MATCH) 

&& (h != 12 

if ( 

; (strcmp ( 

&string[6], "AM" ) 

== MATCH) 

Sc Sc. (h == 12 


h = 0; 


/* Shift bits into the proper position and place them */ 
/* into the time integer. */ 
h = h « 11; 
time = h; 

/* Get the "minutes" portion, convert to integer, */ 

/* shift bits and place them into the time integer. */ 
strncpy ( s, &string[2], 2 ); 
h = atoi ( s ); 
h = h << 5; 
time = time | h; 

/* Process the "seconds" portion of the time. */ 
strncpy ( s, &string[4], 2 ); 
h = atoi ( s ) / 2; 
time = time | h; 

/* Set the system clock to the new time. */ 

Tsettime ( time ); 

/* Get the address of the string containing the date. */ 
string = get_tedinfo_str ( dial addr, DATEFLD ); 
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/* Process the "month" portion. */ 
strncpy ( s, string, 2 ); 
h = atoi ( s ); 
h = h << 5; 
date = h; 

/* Process the "day" portion. */ 
strncpy ( s, &string[2], 2 ); 
h = atoi ( s ); 
date = date | h; 

/* Process the "year" portion. */ 
strncpy ( s, &string[4] ); 
h = atoi ( s ) - 80; 
h = h « 9; 
date = date | h; 

/* Set the system to clock to the new date. */ 
Tsetdate ( date ); 

} 


/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* get_time () 

* Gets system time and converts it to string format. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

get_time ( string ) 

char *string; /* Pointer to string in which to store time. */ 

{ 

int time, /* Time in system format. */ 

hour, min, sec; /* Time broken down into separate ints. */ 

char s[3];/* "AM" or "PM" */ 

/* Get system time & break down into individual components. */ 

time = Tgettime (); 

sec = ( time & OxOOlf ) * 2; 

min = ( time >> 5 ) & 0x003f; 

hour = ( time >> 11 ) & OxOOlf; 

/* Convert system 24-hour format to regular 12-hour format. */ 
if ( hour > 11 ) { 

strcpy ( s, "PM" ); 
if ( hour > 12 ) 
hour -= 12; 

} 

else { 

strcpy ( s, "AM" ); 
if ( hour == 0 ) 
hour = 12; 

} 

/* Convert and add hours to time string. */ 
if ( hour < 10 ) { 

string[0] = 'O'; 

sprintf ( &string[l], "%d", hour ); 

} 

else 

sprintf ( string, "%d", hour ); 

/* Convert and add minutes to time string. */ 
if ( min < 10 ) { 
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string[2] = 'O'; 

sprintf ( &string[3], "%d", min ); 

} 

else 

sprintf ( &string[2], "%d", min ); 

/* Convert and add seconds to time string. */ 
if ( sec < 10 ) { 

string[4] = 'O'; 

sprintf ( &string[5], "%d", sec ); 

} 

else 

sprintf ( &string[4], "%d", sec ); 

/* Add "AM" or "PM" to time string. */ 
strcpy ( &string[6], s ); 

} 

j '^•k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k'k-k'k-k'k-k'k-k'k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k'k'k 

* get_date () 

* Gets system date and converts it to string format. 

■k'k-k-k-k'k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k'k-k-k-k'k-k-k-k'k-k-k'k-k-k'kj 

get_date ( string ) 

char *string; /* Pointer to string that will contain the date. */ 

{ 

int date,/* Date in system format. */ 

day, mnth, year; /* Date broken into components. */ 

/* Get system date and convert to individual components. */ 

date = Tgetdate (); 

day = date & OxOOlf; 

mnth = (date >> 5) & OxOOOf; 

year = ((date >> 9) & 0x007f) + 80; 

year = year % 100; 

/* Convert and add "months" portion to date string. */ 


if ( 

mnth < 10 

) { 





string[0] 

= 'O'; 




} 

else 

sprintf 1 

[ &string[l 

], "%d" , 

mnth ); 



sprintf 1 

; string, " 

%d" , mnth ); 


/* convert and 

add "days" 

portion 

to date 

string 

if ( 

day < 10 ) 

{ 





string[2] 

= 'O'; 




} 

else 

sprintf 1 

[ &string[3 

], "%d" , 

day ) ; 



sprintf 1 

[ &string[2 

], "%d" , 

day ) ; 


/* Convert and 

add "year" 

portion 

to date 

string 


sprintf ( &string[4], "%d", year ); 


I'k-k'k-k'k-k'k-k'k-k'k-k-k-k'k-k'k-k'k-k'k-k-k'k-k'k-k'k-k'k'k'k-k'k-k-k-k-k-k-k-k'k-k'k-k'k-k'k-k'k-k'k-k 
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* get_tedinfo_str () 

* Returns a pointer to an editable string in a 

* dialog box. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

char *get_tedinfo_str ( tree, object ) 

OBJECT *tree; /* Address of dialog box. */ 

int object; /* Object that contains the string. */ 

{ 

TEDINFO *ob tedinfo; /* Pointer to a tedinfo structure. */ 

ob_tedinfo = (TEDINFO *) tree[object].ob_spec; 
return ( ob_tedinfo->te_ptext ); 

} 


Ikkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* open vwork () 

* Opens a virtual workstation. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkj 

open vwork () 

{ 

int i; 

/* Get graphics handle, initialize the GEM arrays and open*/ 
/* a virtual workstation. */ 

handle = graf_handle ( &dum, &dum, &dum, &dum); 
for ( i=0; i<10; work in[i++] = 1 ); 
work in[10] = 2; 

v__opnvwk ( work in, Shandle, work-out ) ; 

} 

Program Listing #2 

#define DATEDIAL 0/* TREE */ 

#define TIMEFLD 2/* OBJECT in TREE #0 */ 

#define DATEFLD 3/* OBJECT in TREE #0 */ 

#define OKBUTN 4/* OBJECT in TREE #0 */ 

#define CANBUTN 5/* OBJECT in TREE #0 */ 
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Program Listing #3 


ST Basic 


100 OPEN"R" ,#1, "A:DATE.RSC" ,16:FIELD#1,16 AS B$ 

110 A$=" " :FOR 1=1 TO 16:READ V$:IF V$="*" THEN 140 
120 A=VAL ("&H"+V$) :PRINT "*" ;:A$=A$+CHR$(A):NEXT 
130 LSET B$=A$:R=R+1:PUT l,R:GOTO 110 
140 CLOSE 1:PRINT:PRINT "ALL DONE!" 

1000 data 00,00,00,D4,00,80,00,80,00,80,00,00,00,24,00, 
1010 data 00,00,01,64,00,06,00,01,00,03,00,00,00,00,00, 
1020 data 00,00,01,68,44,41,54,45,20,41,4E, 44,20,54,49, 
1030 data 45,00,00,00,30,30,30,30,30,30,41,4D, 00,54,69, 
1040 data 65,3A, 20,5F, 5F,3A,5F,5F,3A,5F,5F,20,5F,5F,00, 
1050 data 39,39,39,39,39,41,41,00,30,30,30,30,30,30,00, 
1060 data 61,74, 65,3A,20,5F,5F,2F,5F,5F,2F,5F,5F, 00,39, 
1070 data 39,39,39,39,00,4F,4B,00,43,41,4E,43,45,4C,00, 
1080 data 00,00,00,24,00,00,00,32,00,00,00,33,00,03,00, 
1090 data 00,02,11,80,00,00,FF,FF,00,0E,00,01,00,00,00, 
1100 data 00,00,00,3D,00,00,00,4F,00,03,00,06,00,00,11, 
1110 data 00,00,FF,FF,00,09,00,12,00,00,00,58,00,00,00, 
1120 data 00,00,00,6E,00,03,00,06,00,00,11,80,00,00,FF, 
1130 data 00,07,00,OF,FF,FF,00,01,00,05,00,14,00,00,00, 
1140 data 00,02,11,21,00,00,00,00,00,29,00,0C,00,02,FF, 
1150 data FF,FF,00,16,00,00,00,20,00,00,00,80,00,02,00, 
1160 data 00,25,00,01,00,03, FF, FF, FF,FF,00, ID, 00,08,00, 
1170 data 00,00,00,9C,00,0C,00,03,00,11,00,01,00,04,FF, 
1180 data FF, FF, 00, ID, 00,08,00,00,00,00,00, B8,00,0D,00, 
1190 data 00,0E, 00,01,00,05,FF,FF,FF,FF,00,1A, 00,05,00, 
1200 data 00,00,00,75,00,02,00,09,00,11,00,01,00,00,FF, 
1210 data FF,FF,00,1A,00,27,00,20,00,00,00,78,00,16,00, 
1220 data 00,11,00,01,00,00,00,D4,00,00,00,00,00,00,00, 
1230 data * 


80 

00 

4D 

6D 

39 

44 

39 

00 

06 

34 

80 

5F 

FF 

30 

FF 

01 

00 

FF 

05 

20 

FF 

09 

00 


Program Listing #4 


ST Check BUG Data for Listing #3 


100 data 469,544,391,421,536,623,487,693,656,884,5704 
1050 data 644,872,720,503,703,556,707,710,686,685,6786 
1150 data 679,860,716,758,875,677,722,530,196,6013 
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CHAPTER 23 - Desk Accessories with Built-In Resource Trees 


In chapter 22 we looked at a short utility that will set the ST's date and time. Although that program 
works fine when run from the Desktop, it would be more convenient to have it as a desk accessory, 
so that it would be available to us from within other GEM programs. Programming a desk accessory 
isn't much more complicated than programming any other GEM application, but, in the case of our 
Date/Time utility, there arises one complication. 

How often have you seen a desk accessory that requires a .RSC file? Not too often. Oh, there's a 
couple of them floating around, but it is not a good programming practice to force a desk accessory 
to rely on a .RSC file — and for a very good reason. 

A desk accessory, once it has been loaded, is constantly active. Even if you haven't selected it from 
the Desk drop-down menu, it is still running, waiting for the cue that will set it in motion. In fact, the 
only way to terminate a desk accessory is to shut off your machine. 

Now think about what we know about .RSC files. They have to be loaded into the ST's memory with a 
call to rsrc_load(), but more importantly, the memory the resource file takes up has to be returned to 
the system at the termination of a program by a call to rsrc_free(). Since a desk accessory is always 
"running," when do we return the memory used by our resource trees? 

I know what you're thinking. "What difference does it make whether or not we ever call rsrc_free() 
when the only way to terminate a desk accessory is to turn the machine off? I mean, last time I 
heard, turning off the machine was a great way to release all the memory!" Right you are. But there 
is one situation where a desk accessory gets reinitialized: when you switch resolutions. If your desk 
accessory has to load a resource file, then each time you switch resolutions, more memory will be 
taken up, because the resource is being reloaded, even though the old one hasn't been released. 

So before we can convert our Date/Time utility to a desk accessory, we have to build our resource 
tree right into the program. How complicated this process will be depends on what tools you have 
available. If you have a resource construction program that'll save your object trees out in source 
code form, then you're three-quarters of the way there. All you have to do is plug in a few addresses, 
and you're on your way. If you don't have access to an RCP that will do this for you, you'll have to 
write your resource by hand, a tedious project indeed. 

In either case, though, we're going to have to have a clear understanding of resource trees in order 
to get our desk accessory's dialog box working. This means we'll be doing a review of some material 
and applying what we learn directly to our Date/Time utility. 

Our Resource Tree 

Take a look at Listing 1. Near the top you'll see some data labeled "Resource tree." This is all the data 
for our dialog box as it was saved from Atari's RCS2 in source code form. (Actually, RCS2 isn't too 
bright and saves data for everything, even data structures not used in our tree. I've already deleted 
the unneeded data for the sake of clarity.) 

At the top of the data, you'll see an array of pointers called rs_strings[], (Even though the strings 
themselves are shown in this array, we still have an array of pointers here, each pointer holding the 
address of its associated string.) These pointers point to all the strings we need for our dialog box, 
with some of the objects being allotted three strings. (The first nine strings shown are actually three 
groups of three.) Why three? Because editable text fields require not only a text string but a format 
template and validation string, as well. Remember? 

The first string shown in rs_strings[] is our dialog box's title line. We don't want an editable text field 
here so the format and validation strings (the second and third strings shown in rs_strings[]) are 
empty. The next group of three strings is for the time field of our dialog box. First is the te_ptext 
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string (the text that will be displayed when the dialog box is first drawn and the area where the text 
the user enters will be found after he exits the dialog box), followed by the te_ptmplt string (the 
uneditable text that is displayed in the text field), and the te_pvalid string (the string that determines 
what type of data is allowable in each position of the string). If all of this is confusing, please review 
Chapters 14 and 15 on dialog boxes. 

The next three strings are the te_ptext, te_ptmplt, and te_pvalid strings for our dialog box's date 
field. And finally there is the text for our OK and CANCEL buttons. 

Following rs_strings[] is another array called rs_tedinfo[]. As you can tell by the name of the array, 
the data here makes up the tedinfo structures for the editable text strings in our dialog box. If you 
think back, you'll remember that a tedinfo structure contains all the information GEM needs to draw 
and handle editable text fields. There are three tedinfos contained in rs_tedinfo[], one each for our 
dialog's title, time, and date fields. 

The first three long words of a tedinfo structure are pointers to the object's te_ptext, te_ptmplt, and 
te_pvalid strings, respectively. If you look at the first three long words in the first tedinfo structure 
shown in rs_tedinfo[], you'll see that we've got the values OL, 1L, and 2L. These don't look very much 
like pointers, do they? That's because they're not! They are actually offsets into the rs_strings[] array, 
telling us which pointers we need to place in the tedinfo structure. 

This tedinfo is for our dialog's title field. We are told here that the te_ptext string for this field is 
pointed to by element 0 of the rs_strings[] array, and the te_ptmplt and te_pvalid strings for this 
field are pointed to by elements 1 and 2, respectively. When we initialize our desk accessory, it is up 
to us to see that the right pointers get placed into the tedinfo. 

The next six members of the tedinfo structure contain (in order) the font size, a reserved word, the 
horizontal justification of the text, color information, another reserved word, and the you'll see the 
value 0x21121L. This value contains information on the box's color and border thickness. It doesn't 
hold a pointer to a tedinfo because a G_BOX contains no editable text. 

But look at the second object in the tree. This is our dialog's title field, and if we look up the 
G_BOXTEXT object type in our reference materials, we'll find that the ob_spec field of this type of 
object does hold a pointer to a tedinfo structure. If you look at the ob_spec field for this object in our 
listing, you'll see the value OxOL which is obviously not a pointer. Again, this is an offset, telling us 
that the tedinfo for our title field is element 0 of the rs_tedinfo[] array. 

The next two objects in our tree, the time and date fields, also contain offsets in the ob_spec 
member, telling us that the tedinfos for these objects are element 2 and 3 of the rs_tedinfo[] array. 

The last two objects in our tree are the OK and CANCEL buttons. They are objects of the type 
G_BUTTON, and if we look up these objects in our reference materials, we'll find that their ob_spec 
fields should contain not a pointer to a tedinfo, but instead a pointer to the string that will be 
displayed in the button. Looking at the ob_spec fields in the button objects, we see that we once 
again have some offsets, 0x9L and OxAL. These values tell us that the pointers to the button strings 
are found in element 9 and 10 of the rs_strings[] array. 

The last four members of our object structures contain the X coordinate, Y coordinate, width, and 
height of the objects. It's important to note that these values are given as character coordinates 
rather than pixel coordinates. This is because the resource construction program has no idea what 
resolution we'll be running the program in. We must adjust these values so that the dialog box is 
drawn properly for whatever resolution in which we happen to be. 

Our code-resident resource tree is concluded with the array rs_trindex[j. This array will contain the 
addresses of each of the separate trees that make up our resource tree. In our case, we have only 
one tree, a dialog box, so this array contains space for only one entry. Had we had several trees — for 
instance, three dialog boxes — this array would have had places for the addresses of each. 
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If you look at the value stored in the rs_trindex array, you will see that, once again, we are dealing 
with an offset, OL. This tells us that the address of object 0 of rs_object[] should be placed in this 
element of the array. 

Writing a Desk Accessory 

As I said before, writing a desk accessory is a fairly simple process. As we've done with our Time/Date 
utility, we can actually write the program as a normal GEM application, and then, once we've got it 
running, convert it to a desk accessory. 

Listing 1 is just such a conversion. Most of the program is identical to Chapter 22's, and so, if you 
typed in Chapter 22's listing, you can use most of the code directly in this program. The following 
functions have not changed: chk_date(), set_date(), get_time(), get_date(), get_tedinfo_string(), and 
open_vwork(). When you compile the new version, remember to have the DATE.H file from Chapter 
22 on the same disk with your source code. 

Let's take a look at the function do_acc(), since it is here that we set up our desk accessory, as well as 
initialize our dialog box. The first thing we have to do to get our desk accessory up and running is to 
get its name placed on the menu bar so that the user can select it. This is done with the call 

menu id = menu_register(gl apid," Name "); 

where the integer menujd is the ID number of our desk accessory returned from the call to 
menu_register() and the integer gl_apid is the application ID assigned by appl_init(). We don't have 
to worry about retrieving the value of gl_apid ourselves; we just define it as an external variable, 
much like the GEM global arrays. 

Once we've got our accessory registered on the menu bar, we must initialize the dialog box. This 
requires replacing the offsets in the various structures with the proper pointers and changing the 
object coordinates and sizes from character form to pixel form. 

First, we store the address of our resource tree into the rs_trindex[] array, which is done like this: 

rs_trindex[0] = (long) rs^object; 

Had we had two object trees in our resource, we would have had to fill in an address for 
rs_trindex[l], too. Because we have six objects in our dialog box, the first object of a second tree (if it 
existed) would be the seventh object in the rs_object[] array, and we would have stored its address 
like this: 

rs_trindex[1] = (long) &rs_object[6]; 

The addresses of additional trees are stored in the same way, each address being placed in the next 
element of rs_trindex[] and each address being derived from the element of rs_objects[] that 
contains the first object in the object tree. 

Now we move down one step in the hierarchy from the tree to the objects in the tree. Five of our 
objects require that the ob_spec fields be filled in with pointers. The first three — the title, time, and 
date fields -- require pointers to tedinfos. Using the offsets that the resource construction program 
left for us, we initialize these fields using this method: 

rs_object[1].ob_spec = (char *) &rs_tedinfo[0]; 

In English the above code says, "The ob_spec field of the second object in the array rs_object[] gets 
the value of a pointer to character, and that pointer points to the first tedinfo structure in the array 
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rs_tedinfo[]." Yikes! I think I liked the C version better! Anyway, we initialize the other two tedinfo 
pointers the same way, as you can see in Listing 1. 

Next we have two objects -- the OK and CANCEL buttons — that must have pointers to strings placed 
in their ob_spec fields. The code that accomplishes that job (for one of the buttons) looks like this: 

rs_object[4].ob_spec = rs_strings[9]; 

Once again in English, the above says, "The ob_spec field of the fifth object in the array rs_object[] 
gets the string pointer stored in element 9 of the array rs_strings[j." 

Now we have to take another step down in our hierarchy and initialize our tedinfo structures. We 
have three of them that must have pointers to their te_ptext, te_ptmplt, and te_pvalid strings filled 
in. We do that with code similar to what we used for the ob_spec pointers above, like this: 

rs_tedinfo[0].te_ptext = rs_strings[0]; 
rs_tedinfo[0].te_ptmplt = rs_strings[l]; 
rs_tedinfo[0].te_pvalid = rs_strings[2]; 

The other tedinfos are handled the same way. 

Now all we have left to do is convert the dialog's character coordinates to pixel coordinates. Luckily, 
there's a function that does that dirty work for us. The call 

rsrc_obfix( tree_addr, object ); 

where tree_addr is the address of the object tree and the integer object is the index of the object 
within the tree, does all the conversions for us. In Listing 1, we've used a for loop to adjust all six 
objects with a single statement. 

Waiting Forever 

As I said before, a desk accessory, once installed on the menu bar, waits to be called by the user. 
When the user clicks on the desk accessory's entry on the menu bar, the desk accessory is notified by 
a message from GEM. What we need to do is construct a while loop that'll loop "forever." In that 
loop we'll check to see if we've received a GEM message. 

Once we get a message (in this case, from a call to evnt_mesag()), we'll check to see if the message 
type (stored in msg_buf[0]) is an AC_OPEN message. An AC_OPEN message is sent by GEM whenever 
a desk accessory menu entry is clicked on by the user. When we receive this message, we then have 
to compare the menu ID sent to us in msg_buf[4] with the menu ID we obtained with our call to 
menu_register(). If they match, we go ahead and bring up our dialog box so that the user can edit the 
date and time. 

And that's about all there is to it. I should mention that there is also a AC_CLOSE message that is sent 
to your desk accessory when the desk accessory is closed. This message is important if you're using 
windows in the desk accessory because GEM automatically closes these windows when it returns to 
the desktop. Without the AC_CLOSE message, you'd have no way of knowing when to reset any 
window flags or other related data items you may need to update. Both the AC_OPEN and AC_CLOSE 
messages are defined in the GEMDEFS.H file. 

The Desk Accessory Link 

One last note: Whenever you link a program with Megamax C, some start-up code (contained in the 
INIT.O file) is automatically linked to your object file. Desk accessories, however, have to be 
initialized differently when they are run, so require different start-up code. The desk accessory Start- 
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up code is contained in the ACC.L file supplied with the Megamax compiler. (Other compilers will 
have their own versions of the start-up module.) The source code for your desk accessory is compiled 
in the same manner as any other program, but when you get to the link step, you must be sure to 
select ACC.L as the first file in your link list. If you don't, your desk accessory will not run. 

NOTE FOR LASER C USERS: The new version of Megamax C, Laser C, no longer needs the separate 
ACC.L file. To produce an accessory with Laser C, you must compile and link your source code 
separately. After your source code has compiled, go to the LINK dialog box and change the target 
name, below the left file selector, to progname.ACC. The new Laser linker will automatically add the 
special code necessary to produce a working desk accessory. 
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Program Listing #1 

j •k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k J 

/*C-manship, Listing 1*/ 

/* CHAPTER 23 */ 

/*Developed with Megamax C*/ 

J •k'k-k'k-k'k-k'k-k'k-k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k'k-k J 

#include <osbind.h> 

#include <gemdefs.h> 

#include <obdefs.h> 

#include "date.h" 

#define TRUE 1 
#define FALSE0 
#define MATCHO 

/* GEM arrays */ 
int work in [ 11], 

work_out [57], 
contrl[12], 
intin[128], 
ptsin[128], 
intout[128], 
ptsout[128]; 

extern int gl apid; /* Global application ID. */ 

int handle,/* Application handle. */ 
dum, /* Dummy storage.*/ 
menu id; /* Our accessory's ID. */ 
char *get_tedinfo_str (); 

int msg_buf[8]; /* Message buffer. */ 

OBJECT *datedial_addr; /* Pointer to dialog box. */ 

I •k-k'k-k'k-k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k-k'k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k-k'k-k'k-k 

* Resource tree 

'k-k-k-k'k-k'k-k'k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k'k-k'k-k-k'k-k-k-k-k-k-k-k'k-k-k-k'k-k'k-k'k-k-k-k! 


char *rs strings[] = { 
"DATE AND TIME", 

I! fl 

r 

ii ii 

t 

"000000AM" , 

"Time: _:_ 

"999999AA" , 

" 000000 ", 

"Date: _/_/_" 

"999999", 

"OK", 

"CANCEL"} ; 


TEDINFO rs tedinfo[] = { 


0L, 

1-3“ 

\— 1 

2L, 

3, 

6, 

2, 

0x1180, 

0x0, 

-1, 

\— 1 

\— 1 

3L, 

4L, 

5L, 

3, 

6, 

0, 

0x1180, 

0x0, 

-1, 

9, 18, 

6L, 

7L, 

l-q 

CO 

3, 

6, 

0, 

0x1180, 

0x0, 

-1, 

7,15}; 


OBJECT rs_object[] = { 
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-1, 

1, 

5, 

G BOX, NONE, 0x30, 0x21121L 

o 

o 

41,12 

r 


2, 

-1, 

-1, 

G_ 

BOXTEXT, NONE, SHADOWED, 

OxOL, 

2,1, 

37, 

1, 

3, 

-1, 

-1, 

g" 

FTEXT, EDITABLE, NORMAL, 

OxlL, 

12,3, 

17 

,1, 

4, 

-1, 

-1, 

G^ 

FTEXT, EDITABLE, NORMAL, 

0x2L, 

LO 

CO 
\—1 

14 

,1, 

5, 

-1, 

-1, 

g" 

BUTTON, 0x5, SHADOWED, 0x9L, 2 

\—1 

CTi 

,1, 


0, 

-1, 

-1, 

G 

BUTTON, 0x27, SHADOWED, 

OxAL, 

22,9, 

17, 

l}; 


long rs trindex[] = { 

OL}; 

#define NUMJDBS 6 

/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* Main program. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

main () 

{ 

appl^init (); /* Init application. */ 

open vwork ();/* Open virtual workstation. */ 

do_acc ();/* Go do our thing.*/ 

} 

j •kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* do_acc () 

* Initialize and handle desk accessory. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

do_acc () 

{ 

int x; /* Loop variable. */ 

/* Place our accessory on the menu bar. */ 

menu id = menu_register ( gl_apid, "Date/Time " ); 

/* Initialize resource tree. */ 
rs_trindex[0] = (long) rs_object; 
datedial_addr = (OBJECT *) rs_trindex[0]; 
rs_object[1].ob_spec = (char *) &rs_tedinfo[0]; 
rs_object[2].ob_spec = (char *) &rs_tedinfo[1]; 
rs_object[3].ob_spec = (char *) &rs_tedinfo[2]; 
rs_tedinfo[0].te_ptext = rs_strings[0]; 
rs_tedinfo[0].te_ptmplt = rs_strings[1]; 
rs_tedinfo[0].te_pvalid = rs_strings[2]; 
rs_tedinfo[1].te_ptext = rs_strings[3]; 
rs_tedinfo[1].te_ptmplt = rs_strings[4]; 
rs_tedinfo[1].te_pvalid = rs_strings[5]; 
rs_tedinfo[2].te_ptext = rs_strings[6]; 
rs_tedinfo[2].te_ptmplt = rs_strings[7]; 
rs_tedinfo[2].te_pvalid = rs_strings[8]; 
rs_object[4].ob_spec = rs_strings[9]; 
rs_object[5].ob_spec = rs_strings[10]; 

/* Set all the objects' coordinates. */ 
for ( x=0; x<NUM_OBS; ++x ) 

rsrc_obfix ( datedial_addr, x ); 

/* Wait forever for messages. */ 
while ( 1 ) { 

evnt mesag ( msg buf ); 

switch ( msg_buf[0] ) {/* msg_buf[0] is message type. */ 


Port: HYPertext by Lonny Pursell & PDF by DrCoolZic (jig) - VI.0 Oct. 2010 


Page 228/321 


C-MANSHIP COMPLETE - by CLAYTON WALNUT 


/* Open our accessory. */ 
case ACJDPEN: 

if ( msg buf[4] == menu id ) 
do date () ; 


/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* do_date () 

* Loads the resource file and handles the dialog box. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

do_date () 

{ 

int dial x, /* Dialog's X coord.*/ 

dial_y, /* Dialog's Y coord.*/ 
dial_w, /* Dialog's width.*/ 
dial h, /* Dialog's height. */ 

choice, /* Exit button clicked from dialog. */ 
okay; /* Flag indicating if entered date valid. */ 


char date_str[8],/ * String to hold date. */ 

time str[10]; /* String to hold time. */ 

char *string; /* Temp string pointer. */ 


graf mouse ( ARROW, OL ); 

get_time ( time_str ); 
get_date ( date_str ); 

/* Copy system time and date into dialog box, */ 
string = get_tedinfo_str ( datedial_addr, TIMEFLD ); 
strcpy ( string, time_str ); 

string = get tedinfo_str ( datedial addr, DATEFLD ); 
strcpy ( string, date_str ); 

/* Prepare dialog box for drawing, and init flag. */ 
form_center(datedial_addr,&dial_x,&dial_y,&dial_w,&dial_h); 
form dial(FMD^START,0,0,10,10,dial_x,dial y,dial_w,dial h); 
okay = TRUE; 

/* This loop repeats until the user clicks the CANCEL */ 

/* or until the user enters a valid date and clicks OK. */ 
do { 

/* Draw dialog and allow user to manipulate it. */ 

objc^draw(datedial_addr,0,8,dial_x,dial y,dial_w,dial h); 

choice = form do ( datedial_addr, TIMEFLD ); 

/* Reset the state of the chosen button. */ 
datedial addr[choice].ob_state = SHADOWED; 

/* If OK was clicked, check entered date and set system */ 
/* date if date entered is valid, */ 
if ( choice == OKBUTN ) { 

okay = chk_date ( datedial_addr ); 
if ( okay ) 
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set_date ( datedial_addr ); 

} 

} 

while ( okay == FALSE && choice == OKBUTN ); 

/* Get rid of the dialog box. */ 

form^dial(FMD^FINISH,0,0,10,10,dial_x,dial_y,dial_w,dial h); 

} 


/■k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'kic'k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k 

* chk_date () 

* Examines the strings in dialog for a valid date 

* and valid time. 

'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k'k-k/ 

chk date ( dial_addr ) 

OBJECT *dial_addr; /* Address of dialog box. */ 

{ 

int mnth, day, year, /* Date and time broken into integers.*/ 
hour, min, sec, 

space, /* Flag for bad chars in time string. */ 
okay,/* Flag indicating valid time & date. */ 
x; /* Loop variable. */ 

char m[3], d[3], y[3], /* Date & time as character arrays. */ 
h[3], mn[3], s[3], 
ap[3]; /* "AM" or "PM" */ 

char *date_str, /* Pointer to string containing date. */ 

*time str; /* Pointer to string containing time. */ 

/* Init date and time integers to error condition. */ 
mnth = day = year = hour = min = sec = -1; 

/* Get address of string containing date. */ 
date str = get tedinfo^str ( dial_addr, DATEFLD ); 

/* Convert date string to integer format. */ 
if ( strlen ( date_str ) == 6 ) { 

strncpy ( m, date_str, 2 ); 
m [ 2 ] = 0 ; 

strncpy ( d, &date_str[2], 2 ); 
d [ 2 ] = 0 ; 

strncpy ( y, &date_str[4], 2 ); 
y[2] = 0; 

mnth = atoi ( m ); 
day = atoi ( d ); 
year = atoi ( y ); 

} 

/* Get address of string containing time. */ 
time_str = get_tedinfo_str ( dial_addr, TIMEFLD ); 

/* Check for spaces in time string. */ 

space = FALSE; 

for ( x=0; x<6; ++x ) 

if ( time str[x] == ' ' ) 

space = TRUE; 

/* Convert time string to integer format. */ 
if ( (strlen ( time_str ) == 8) && (space ) { 
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strncpy ( h, time_str, 2 ); 
h [ 2 ] = 0 ; 

strncpy ( mn, &time_str[2], 2 ); 
mn[2] = 0; 

strncpy ( s, &time_str[4], 2 ); 
s[2] = 0; 

hour = atoi ( h ) ; 

min = atoi ( mn ); 

sec = atoi ( s ); 

strcpy ( ap, &time_str[6] ); 

} 

/* Examine time and date for validity. */ 
if ( mnth < 1 | mnth >12 | day < 1 | day > 31 

year < 0 | year > 99 | hour < 0 | hour > 23 | min < 0 
min > 59 | sec < 0 | sec > 59 

((strcmp (ap,"AM") !=MATCH) && (strcmp (ap,"PM") !=MATCH))) { 
okay = FALSE; 

form_alert( 1, "[1][Date or time not valid!][CONTINUE]" 



else 

okay = TRUE; 
return ( okay ); 


/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* set_date () 

* Sets the system time and date to the values 

* entered into the dialog box. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

set_date ( dial_addr ) 

OBJECT *dial_addr; /* Address of dialog box. */ 

{ 

char *string; /* Temporary string pointer. */ 
char s[3];/* Temporary string storage. */ 
int h,/* Work variable.*/ 

time, /* Time in system format.*/ 
date; /* Date in system format.*/ 

/* Get address of string containing time. */ 
string = get tedinfo^str ( dial addr, TIMEFLD ); 

/* Extract "hours" portion and convert to integer. */ 
strncpy ( s, string, 2 ); 
h = atoi ( s ); 


/* 

Adjust hour to the 24-hour clock format. 

*/ 


if 

( (strcmp ( &string[6], "PM" ) 
h += 12; 

== MATCH) 

&& 

(h != 12 

if 

( (strcmp ( &string[6], "AM" ) 

== MATCH) 

&& 

(h == 12 


h = 0; 


/* Shift bits into the proper position and place them */ 
/* into the time integer. */ 
h = h « 11; 
time = h; 

/* Get the "minutes" portion, convert to integer, */ 
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/* shift bits and place them into the time integer. */ 
strncpy ( s, &string[2], 2 ); 
h = atoi ( s ); 
h = h << 5; 
time = time | h; 

/* Process the "seconds" portion of the time. */ 
strncpy ( s, &string[4], 2 ); 
h = atoi ( s ) / 2; 
time = time | h; 

/* Set the system clock to the new time. */ 

Tsettime ( time ); 

/* Get the address of the string containing the date. */ 
string = get tedinfo str ( dial_addr, DATEFLD ); 

/* Process the "month" portion. */ 
strncpy ( s, string, 2 ); 
h = atoi ( s ); 
h = h << 5; 
date = h; 

/* Process the "day" portion. */ 
strncpy ( s, &string[2], 2 ); 
h = atoi ( s ); 
date = date | h; 

/* Process the "year" portion. */ 
strncpy ( s, &string[4] ); 
h = atoi ( s ) - 80; 
h = h « 9; 
date = date | h; 

/* Set the system to clock to the new date. */ 

Tsetdate ( date ); 

} 


j •^•k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k-k-k-k-k-k'k-k'k'k-k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k 

* get_time () 

* Gets system time and converts it to string format. 

•k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k-k-k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k J 

get_time ( string ) 

char *string; /* Pointer to string in which to store time. */ 

{ 

int time, /* Time in system format. */ 

hour, min, sec; /* Time broken down into separate ints. */ 

char s[3];/* "AM" or "PM" */ 

/* Get system time & break down into individual components. */ 

time = Tgettime (); 

sec = ( time & OxOOlf ) * 2; 

min = ( time >> 5 ) & 0x003f; 

hour = ( time >> 11 ) & OxOOlf; 

/* Convert system 24-hour format to regular 12-hour format. */ 
if ( hour > 11 ) { 

strcpy ( s, "PM" ); 
if ( hour > 12 ) 
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hour -= 12; 


} 

else { 



strcpy ( 

s, "AM" ); 



if ( hour 

== 0 ) 


} 

hour = 12; 


/* Convert and 

add hours to 

time string. */ 

if ( 

hour < 10 

) { 



string[0] 

= 'O'; 


} 

else 

sprintf ( 

&string[1], 

"%d" , hour ); 


sprintf ( 

string, "%d 

" , hour ); 

/* Convert and 

add minutes 

to time string. */ 

if ( 

min < 10 ) 

{ 



string [2] 

= 'O'; 


} 

else 

sprintf ( 

Sstring[3], 

"%d", min ); 


sprintf ( 

Sstring[2], 

"%d", min ); 

/* Convert and 

add seconds 

to time string. */ 

if ( 

sec < 10 ) 

{ 



string[4] 

= 'O'; 


} 

else 

sprintf ( 

&string[5], 

"%d", sec ); 


sprintf ( 

Sstring[4], 

"%d", sec ); 

/* Add "AM" or 

"PM" to time 

string. */ 


strcpy ( &string[6], s ); 


! ■k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k 

* get_date () 

* Gets system date and converts it to string format. 

'k-k'k-k'k-k'k-k'k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k/ 

get_date ( string ) 

char *string; /* Pointer to string that will contain the date. */ 

{ 

int date,/* Date in system format. */ 

day, mnth, year; /* Date broken into components. */ 

/* Get system date and convert to individual components. */ 

date = Tgetdate (); 

day = date & OxOOlf; 

mnth = (date >> 5) & OxOOOf; 

year = ((date >> 9) & 0x007f) + 80; 

year = year % 100; 

/* Convert and add "months" portion to date string. */ 
if ( mnth < 10 ) { 

string[0] = 'O'; 

sprintf ( &string[l], "%d", mnth ); 

} 

else 

sprintf ( string, "%d", mnth ); 
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/* convert and add "days" portion to date string. */ 
if ( day < 10 ) { 

string[2] = 'O'; 

sprintf ( &string[3], "%d", day ); 

} 

else 

sprintf ( &string[2], "%d", day ); 

/* Convert and add "year" portion to date string. */ 
sprintf ( &string[4], "%d", year ); 

} 

j '^■k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k-k'k-k'k-k'k-k'k-k'k-k'k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k 

* get_tedinfo_str () 

* Returns a pointer to an editable string in a 

* dialog box. 

•k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k-k'k-k'k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k j 

char *get_tedinfo_str ( tree, object ) 

OBJECT *tree; /* Address of dialog box. */ 

int object; /* Object that contains the string. */ 

{ 

TEDINFO *ob tedinfo; /* Pointer to a tedinfo structure. */ 

ob_tedinfo = (TEDINFO *) tree[object].ob_spec; 
return ( ob_tedinfo->te_ptext ); 

} 


j ■^•k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k'k-k'k-k'k-k'k-k'k-k-k-k'k-k'k-k'k-k'k-k'k'k 

* open vwork () 

* Opens a virtual workstation. 

■k'k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k'k-k-k'k-k'k-k'k-k'k-k'k-k'k-k-k-k'kj 

open vwork () 

{ 

int i; 

/* Get graphics handle, initialize the GEM arrays and open*/ 
/* a virtual workstation. */ 

handle = graf handle ( &dum, &dum, &dum, &dum); 
for ( i=0; i<10; work in[i++] = 1 ); 
work in[10] = 2; 

v^opnvwk ( work in, Shandle, work-out ); 

} 


Program Listing #2 

#define DATEDIAL 0/* TREE */ 

#define TIMEFLD 2/* OBJECT in TREE #0 */ 
#define DATEFLD 3/* OBJECT in TREE #0 */ 
#define OKBUTN 4/* OBJECT in TREE #0 */ 
#define CANBUTN 5/* OBJECT in TREE #0 */ 
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CHAPTER 24 - THE GRAPHICS MANAGER LIBRARY 

Certainly all of us have used GEM's various constructions such as windows and dialog boxes. When 
we use these things we don't pay much attention to what is going on. We just take it for granted that 
when we drag the lower-right corner of a window with the mouse pointer the window will get larger, 
or that when we grab its title bar we'll be able to move it about the screen. 

What you may not realize is that these routines that control windows and dialog boxes and the other 
GEM constructions are actually "high-level" routines that call various other "low-level" routines on 
the AES and VDI. We've touched on this subject before when we talked about the VDI and why those 
graphics routines were called "primitives" and when we learned that it's not a good idea to call VDI 
mouse functions if you're using AES functions that may also call the VDI mouse routines. 

Specifically, what we'll be talking about are a few of the AES functions used by windows and dialog 
boxes. We're going to be dropping down a level, as it were, from the sophisticated window and 
dialog routines to some of the functions these routines depend upon in order to do their tricks. 

The Sample Program 

When you run this chapter's program, a large rectangle will be drawn on the screen. The program 
will then wait for input via the mouse. The large rectangle is a border within which all the program's 
activities will be contained. 

Hold down the left mouse button and drag the mouse pointer down to the right. A box that expands 
and contracts with the movement of the mouse pointer will be drawn on the screen. When you 
release the mouse button, the final box will be filled in. In the lower right corner of the box is a small 
button. By placing the mouse pointer over this button and holding down the left button, you'll be 
able to change the size of the box by dragging on its corner. Note that, if you try to resize the box 
beyond the boundary we've set up, the program will ignore your request. 

If you place the mouse pointer inside the box and hold down the left button, the mouse pointer will 
change into a hand that you can use to reposition the box anywhere on the screen, as long as the box 
stays within the border we've drawn. (As a matter of fact, the program won't allow you to drag the 
box outside of the border.) 

To get out of the sample program and back to the Desktop, hold down the right mouse button. 


Deja Vu 

I'm sure you recognize all of the effects we're using in our sample program. We've spent much time 
on our STs moving and sizing boxes. These routines are the foundations upon which the more 
advanced abilities of GEM are built. Fortunately, these routines are available to us as GEM 
programmers, so that we can construct our own specialized, GEM-like routines. 

All of the functions we're using to simulate GEM in this program are part of the AES Graphics 
Manager library. We've used a couple of these functions, like graf_handle() and graf_mouse(), in the 
past. We've also used most of the Graphics Manager's functions indirectly. For instance, when we 
studied dialog boxes, we talked about a function called form_dial() that, among other things, allowed 
us to have a expanding or shrinking box displayed on the screen. The form_dial() function performed 
some of its tricks by calling the graf_growbox() and graf_shrinkbox() functions found in the AES 
Graphics Manager. (Note that all the Graphics Manager functions start with the prefix graf.) If we 
wish to draw an animated expanding box of our own, we use the call 
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graf^growbox( xl, yl, wl, hi, x2, y2, w2, h2 ); 

where the first four arguments are the X coordinate, Y coordinate, width, and height of the starting 
rectangle; and the second four arguments are the X coordinate, Y coordinate, width, and height of 
the final rectangle. This function will return a zero upon failure or a positive integer if successful. Its 
complementary function, the one that draws an animated shrinking box, is called in the same way: 

graf_shrinkbox( xl, yl, wl, hi, x2, y2, w2, h2 ); 


Our Program 

In our sample program, we haven't used graf_growbox() or graf_shrinkbox(), but we have used many 
of the other functions available in the Graphics Manager library. 

Look at the function do_box(). Near the top you'll see a nested while loop. The first while is set up to 
repeat until we receive acceptable coordinates for the box the user wants to draw. The inner while 
loop forces the program to wait for a press of the left mouse button. We continually poll the mouse's 
state until we detect that the button has been pressed. The function call we use to check the 
mouse's state is: 

graf__mkstate (&mouse_x, Smouse^y, &mouse_but, &key_state ); 

where &mouse_x, &mouse_y, &mouse_but, and &key_state are the addresses of the integers that 
will receive the mouse's current X coordinate, the mouse's current Y coordinate, the mouse's current 
button state, and the state of the keyboard's Shift, Control and Alternate keys. The integer 
mouse_but will contain a 1 if the left button was pressed, a 2 if the right button was pressed and a 3 
if both were pressed. The integer key_state will contain a 1 if the right Shift was pressed, a 2 if the 
left Shift was pressed, a 4 if the Control key was pressed, and an 8 if the Alternate key was pressed. 
For multiple key presses, we would just add the appropriate values together. (You remember how to 
handle bit settings, right?) 

When we detect that the left mouse button has been pressed, we get the mouse's coordinates and 
use them as the coordinates for the upper-left corner of the box. The next step, then, is to allow the 
user to drag the mouse to outline the box that he wants. We do this with the call 

graf_rubberbox(box^x, box y, min w, min h, &box_w, &box h); 

where box_x and box_y are the coordinates of the box's upper-left corner, min_w and min_h are the 
box's minimum allowable size in pixels, and &box_w and &box_h are the addresses of integers where 
the final selected width and height of the box will be stored. 

After our call to graf_rubberbox(), we'll have all the information we need to draw the box the user 
selected. But before we actually draw the box, we must check to make sure that the box will fit inside 
our boundary. In the if statement that checks this condition, you'll notice that we're using the values 
stored in work_out[0] and work_out[l]. The work_out[] array is one of our GEM global arrays, and its 
elements were filled in when we initialized the application program. Element 0 of this array contains 
the width of our device (in this case, the device is the screen, so it is measured in pixels), and 
element 1 contains the height of our device. 

Once we've drawn the box, we enter another nested while loop. The outer loop checks for a 
program-exit condition, and the inner loop again polls the mouse. If the right mouse button is 
pressed, we exit the program. If the left mouse button is pressed, we have to check the location of 
the mouse, so that we know whether the user wants to move the box or size it. 
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If the user is holding down the mouse button while on the box's sizing button, we need to call 
graf_rubberbox() again to let the user choose the new size of the box. There are two complications. 
The first is something we've already handled before, and that is that we can't allow the size of the 
new box to exceed the boundary that we've set up. 

The second problem arises when the user chooses to make the box smaller. In this case it isn't good 
enough to just redraw the box at it's new size, because we'll be leaving on the screen parts of the old 
box. To erase the leftovers, we first have to calculate their size and then redraw them in the 
background color. Of course, we could simplify matters by erasing the entire old box before we draw 
the new one, but that's an inelegant solution and one that the user would catch us using, since he'd 
be able to see us erasing the old box. We want our programs to operate so smoothly that they seem 
magical. The entire resizing process is handled in our function size_box(). 

If the user has pressed the left mouse button while within the box (but not on the box's sizing 
button), we have to allow the user to move the box to a new location. Our function move_box() 
illustrates how to do this. 

We can get the new location of a box with the call 

graf_dragbox(box w, box h, box x, box_y,bound x,bound y,bound_w, 
bound h. Send x, &end_y ; 

where the integers box_w and box_h are the box's width and height; box_x and box_y are the 
addresses of integers where the box's new X and Y coordinates will be stored; the integers bound_x, 
bound_y, bound_w, and bound_h are the coordinates, width, and height of the boundary within 
which the box must remain; and &end_x and &end_y are the addresses of integers where the box's 
new X and Y coordinates will be stored. 

Once we get the coordinates of the new box, all we must do is erase the old box and draw the new 
one. 

Some Leftovers 

There are a couple of functions in the Graphics Manager library that we haven't looked at yet. One of 
them is a function that allows you to draw an animated box moving from one location to another. 
The call looks like this: 

graf movebox(box w, box h, old x, old_y, new x, new_y ); 

Here, the integers box_w and box_h are the width and height of the box, the integers old_x and 
old_y are the current X and Y coordinates of the box, and the integers new_x and new_y are the final 
coordinates of the box. Note the spelling of the function call; it's different than the spelling in the 
Megamax manual. If you try to call the function using the manual's spelling, your program will not 
link properly because the linker won't be able to find the label. Anyway, this function is really of 
limited use; I can't think of any place where I've seen it in action. 

Finally, the two remaining functions, graf_slidebox() and graf_watchbox() are used with object trees. 
The first is the function that allows sliders, such as those found in windows, to work; and the second 
allows us to track the mouse in and out of a particular rectangle while the mouse button is held 
down. These functions would be useful should we ever want to write our own custom dialog box 
(form_do()) routines. 
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Put on the Coffee 

This completes our tour of the AES Graphics Manager library. You should now have an even clearer 
idea of how some of GEM's routines work, and you should be able to construct many handy GEM-like 
routines with the information you've learned. 

Program Listing #1 

j •k'k-k-k-k'k-k'k-k'k-k-k-k-k-k'k-k'k-k-k-k'k-k'k-k-k-k-k-k-k'k-k-k-k'k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k J 

/*C-manship, Listing 1*/ 

/* CHAPTER 24 */ 

/*Developed with Megamax C*/ 

/ ikkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk J 

#include <obdefs.h> 

#include <gemdefs.h> 

#define TRUE1 
#define FALSE 0 
#define SOLID 1 
#define PATTERN 2 
#define LEFT1 
#define RIGHT 2 

/* GEM arrays */ 

int work_in[ll], work-out[57] , contrl[12], intin[128], 
ptsin[128], intout[128], ptsout[128]; 

int handle,/* Application handle. */ 
dum; /* Dummy storage.*/ 


jkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* Main program. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkj 

main () 

{ 

appl^init (); /* Init application. */ 

open vwork ();/* Open virtual workstation. */ 

do_box ();/* Go do our thing.*/ 

v_clsvwk ( handle );/* Close virtual workstation.*/ 
appl_exit (); /* Back to the desktop.*/ 

} 

/■k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k 

* do box () 

•k 

* Calls screen setup function and handles the mouse, 

* calling the appropriate box functions based on the 

* mouse's coordinates and button state. 

■k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-kk-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k/ 

do_box () 

{ 

int mouse x,/* Mouse X coordinate. */ 

mouse^y, /* Mouse Y coordinate. */ 
mouse_but,/* Mouse button state. */ 
box_x, /* Selected box X coord. */ 
box_y,/* Selected box Y coord. */ 
box_width, /* Selected width of box.*/ 
box height, /* Selected height of box. */ 
exit, /* Program exit flag.*/ 


Port: HYPertext by Lonny Pursell & PDF by DrCoolZic (jig) - VI.0 Oct. 2010 


Page 238/321 


C-MANSHIP COMPLETE - by CLAYTON WALNUT 


} 


coords_ok;/* Proper coordinates flag.*/ 


setup_scrn (); 

coords_ok = FALSE; 

graf jnouse ( ARROW, OL ); 

/* Wait for box coordinates within the boundary. */ 
while ( !coords ok ) { 

/* Poll for left button press. */ 

mouse_but = 0; 

while ( mouse but != LEFT ) 

grafjmkstate ( &mouse_x, &mouse_y, &mouse_but, &dum ); 

/* Get coordinates for the box. */ 
box x = mouse x; 
box_y = mouse_y; 

graf rubberbox(box x,box_y,20,20,&box width,&box height); 

/* Allow only a box whose size fits within the */ 

/* boundary to be drawn. */ 

if ( box x > 20 && box x + box width < work-out[0]-21 && 

box y > 20 && box_y + box height < work out[1]-21 ) { 

draw box ( box x, box_y, box_width, box height ); 
coords__ok = TRUE; 

} 

} 

exit = FALSE; 
while ( lexit ) { 

mouse_but = 0; 

/* Wait for press of left or right mouse button. */ 
while ( mouse but != LEFT && mouse but != RIGHT ) 

grafjmkstate ( Smouse_x, Smousej, &mouse_but, &dum ) ; 

if ( mouse but == LEFT ) 

/* If the mouse was on the sizing button, */ 

/* allow the user to resize the box.*/ 
if ( chose_size ( mouse x, mousej, boxj, box_y, 
box width, box height ) ) 

size box ( box x, box_y, &box_width, &box height ); 

/* If the mouse was anywhere else in the */ 

/* box, allow the user to move the box.*/ 

else if ( chose move ( mouse x, mousej, box x, box y, 
box_width, box height ) ) 

move box ( &box x, &box y, box_width, box height ); 


} 


if ( mouse_but == RIGHT ) 
exit = TRUE; 


/-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k 

* draw_box () 

k 

* Draws a shaded box with a button in the lower right 

* corner.The input is the X and Y coordinates of 

* the box's upper left corner and its width and height. 
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kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

draw box ( x, y, w, h ) 
int x, y, w, h; 

{ 

int pxy[4]; 

graf_mouse ( M_OFF, OL ); 

/* Draw the main body of the box. */ 

vsf interior ( handle, PATTERN ); 

vsf_style ( handle, 5 ); 

vsf color ( handle, BLACK ); 

pxy[0] = x; 

pxy[1] = y; 

pxy[2] = x + w - 1; 

pxy [3] = y + h - 1; 

v_bar ( handle, pxy ); 

/* Draw the box's sizing button. */ 
vsf interior ( handle, SOLID ); 
pxy[0] =x+w- 10; 
pxy[1] =y+h- 10; 
v_bar ( handle, pxy ); 

graf_mouse ( M_ON, OL ); 

} 


/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* size_box () 

k 

* Resizes a box.The input is the X and Y coordinates 

* of the box and pointers to its width and height.The 

* function returns the new width and height by way 

* of the pointers, thus replacing the old values of 

* the width and height. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

size_box ( x, y, w, h ) 
int x, y, *w, *h; 

{ 

int old w, old h; 
int pxy[4]; 

old w = *w; 
old h = *h; 

/* Get the new box size. */ 
graf_rubberbox ( x, y, 20, 20, w, h ); 

/* Don't allow the new box to exceed the boundary. */ 
if ( x + *w > work out[0]-20 | y + *h > work out[l]-20 ) { 

*w = old_w; 

*h = old_h; 

} 

/* If the size is okay, draw the box. */ 
else { 

draw^box ( x, y, *w, *h ); 

/* Erase the leftover portions (if */ 

/* any) of the old box.*/ 
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graf_mouse ( M_OFF, OL ); 
vsf_interior ( handle, SOLID ); 
vsf_color ( handle, WHITE ); 
if ( *w < old_w ) { 

pxy[0] = x + *w; 
pxy[1] = y; 

pxy[2] = x + oldw - 1; 

pxy[3] = y + oldh - 1; 

v^bar ( handle, pxy ); 

} 

if ( *h < old h ) { 

pxy[0] = x; 
pxy[1] = y + *h; 

pxy[2] = x + old_w - 1; 

pxy[3] = y + old_h - 1; 

v__bar ( handle, pxy ) ; 

} 

graf_mouse ( M_ON, OL ); 

} 

} 

/ 'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k'k-k 

* move^box () 

■k 

* Repositions a box.The input is a pointer to the 

* box's X coord., a pointer to the box's Y coord., and 

* the box's width and height.The new X and Y 

* coordinates are returned from the function by way of 

* the pointers, thus replacing the old X and Y values. 

' k'k-k'k-k'kk'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'kj 

move^box ( x, y, w, h ) 
int *x, *y, w, h; 

{ 

int old_x, old_y; 
int pxy[4]; 

old x = *x; 
old_y = *y; 

graf_mouse ( FLAT_HAND, OL ); 

/* Get new location for the box. */ 
graf dragbox ( w, h, *x, *y, 21, 21, 

work-out[0]-41, work_out[1]-41, x, y ); 

/* Erase the old box. */ 

graf_mouse ( M^OFF, OL ); 

vsf color ( handle, WHITE ); 

vsf interior ( handle, SOLID ); 

pxy[0] = oldx; 

pxy[1] = old_y; 

pxy[2] = old x + w - 1; 

pxy[3] = old_y + h - 1; 

v_bar ( handle, pxy ); 

/* Draw the new box. */ 
draw box ( *x, *y, w, h ); 

graf_mouse ( M_ON, OL ); 
graf mouse ( ARROW, OL ); 

} 
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/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* chose_size () 

k 

* Returns a boolean value based on whether the mouse 

* button was pressed while over the box's sizing 

* button.The input is the X and Y coordinates of 

* the mouse, the X and Y coordinates of the box, and 

* the width and height of the box. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

chose size ( mx, my, bx, by, bw, bh ) 
int mx, my, bx, by, bw, bh; 

{ 

if ( mx>bx+bw-10 && mx<bx+bw && my>by+bh-10 && my<by+bh ) 
return ( TRUE ); 

else 

return ( FALSE ); 

} 

/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* chose_move () 

k 

* Returns a boolean value based on whether the mouse 

* button was pressed while over an area of the box 

* other than the sizing button.The input is the X 

* and Y coordinates of the mouse, the X and Y 

* coordinates of the box, and the width and height of 

* the box. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkj 

chose move ( mx, my, bx, by, bw, bh ) 
int mx, my, bx, by, bw, bh; 

{ 

if ( mx>bx && mx<bx+bw && my>by && my<by+bh ) 
return ( TRUE ); 

else 

return ( FALSE ); 

} 

Jkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* setup_scrn () 

k 

* Prepares the screen by clearing the workstation and 

* drawing a border. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

setup_scrn () 

{ 

int pxy[10] ; 

graf_mouse ( M_OFF, 0L ); 

/* Erase the screen. */ 
v_clrwk ( handle ); 

/* Draw the border. */ 
pxy[0] = 20; 
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pxy | 

:i] = 

20; 



pxy | 

:2] = 

work out| 

[0] 

- 20; 

pxy | 

:3] = 

20; 



pxy | 

:4] = 

work out| 

[0] 

- 20; 

pxy | 

:s] = 

work out| 

[1] 

- 20; 

pxy | 

:6] = 

20; 



pxy | 

:7] = 

work out| 

[1] 

- 20; 

pxy | 

:8] = 

20; 



pxy | 

:9] = 

20; 



v pline 

( handle. 

5, 

pxy ) ; 


graf_mouse ( M_ON, OL ); 


! -kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* open vwork () 

* Opens a virtual workstation. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

open vwork () 

{ 

int i; 

/* Get graphics handle, initialize the GEM arrays and open*/ 
/* a virtual workstation. */ 

handle = graf_handle ( &dum, &dum, &dum, &dum); 
for ( i=0; i<10; work in[i++] = 1 ); 
work in[10] = 2; 

v_opnvwk ( work in, Shandle, work-out ); 

} 
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CHAPTER 25 - THE MYSTERY OF COMPILE AND LINK 

A while ago, someone came up to me at a users' group meeting and told me that he was confused 
about what actually goes on during a compilation and link, as well as about the different types of files 
we must manipulate when programming in C -- specifically, .0 and .H files. Luckily for you (he said, 
tongue in cheek), I couldn't resist turning that question into a chapter for C-manship. So we're going 
to take a short break from programming and dig into the innards of these wonderful programs we 
call compilers. 

Stating the Obvious 

There is one thing that we all have to know before we can go any further with this topic. To some 
what I'm about to say may be an obvious fact, to others it may come as a revelation. But whatever 
group you may fall into, this fact is essential in understanding how your C compiler actually works. 

Fact: Every computer understands only one language, machine language, and every program, no 
matter what language it's written in, must sooner or later be reduced to machine language. Of 
course, to completely understand the above fact, we must know exactly what machine language is. If 
you were to get a listing of a machine-language program, what you would have would be a long list 
of numbers. There would be no variable names, no labels of any kind, no strings of characters. 
Nothing but numbers. Those numbers represent the instructions the machine understands and the 
data it needs to perform those instructions. And if we wanted to get very literal about all this, the 
numbers in our list would all be binary numbers — that is, consisting of nothing but zeros and ones. 
Usually, to make things easier for the programmer, "memory dumps" produce listings in hexadecimal 
format. 

How a program is converted to machine code varies with the language we're using. For example, 
when we run an uncompiled BASIC program, each statement in the program is converted into 
machine language as it's encountered, rather than the whole program being converted at once. This 
on-the-fly conversion is why BASIC programs are so slow. BASIC is an example of an "interpreted" 
language. 

Assembly-language programs are as close to machine language as you can get. Each assembly- 
language statement represents a single machine-language instruction. For this reason, many people 
confuse the terms "assembly language" and "machine language," but they are really not the same. 
Assembly language uses "mnemonics" (easy-to-remember names) for each of the machine-language 
instructions to make it easier for programmers to remember them. An assembly-language program is 
not interpreted; it is "assembled." During the assembly process, each of the mnemonics is converted 
to its machine-language equivalent. 

Finally, we get to "compiled" languages, of which C is one. When a program is compiled, all the 
instructions in the source code are converted into machine language, so that we end up with a 
runnable program, one that doesn't need to be interpreted. The difference between a language like 
C and a language like assembly is that C source code does not have the direct one-to-one relationship 
with machine language that assembly source code does. A single statement in C may be compiled 
into several machine language instructions. Still, C programs run much faster than BASIC programs, 
because the entire conversion is done before the program is run. 

Compilation 

What exactly goes on during a compilation depends on the compiler you're using. There are no set 
rules, except that it's the compiler's responsibility to take the source code and turn it into object 
code, the machine-language version of the program. To accomplish this, some compilers make 
several "passes" over the source code, while others, such as Megamax C, make only one pass. 


Port: FlYPertext by Lonny Pursell & PDF by DrCoolZic (jig) - VI.0 Oct. 2010 


Page 244/321 


C-MANSHIP COMPLETE - by CLAYTON WALNUT 


The one-pass compiler is much faster than the others, but that speed comes with certain 
disadvantages. For instance, a multi-pass compiler usually converts the source code into assembly 
code, then assembles the assembly code into the object code. (The Alcyon compiler works this way.) 
One of the advantages of this multi-step process is that the assembly code that is produced by the 
compiler can be modified by the programmer before it is assembled and linked. This way, the 
programmer can do some code optimizing on sections of the program that may not run as fast as 
he'd like. In addition, the assembly-language listings produced by the compiler can be helpful in 
locating hard-to-find bugs in the program (assuming, of course, that you are familiar with 68000 
assembly language). 

The Megamax compiler is a one-pass compiler. It takes our source code and converts it directly into a 
machine-language module. Because no assembly-language file is created during the compilation, we 
don't have the option of "tweeking" the program. However, to make up for this, Megamax allows us 
to place assembly-language code directly into our source code, allowing us to speed up sections of 
our programs that may need optimizing. In addition, we can use a disassembler to turn the object 
module into assembly code. 

Another important thing we need to know about the compiler is that it can substitute machine- 
language instructions only for text within the source code that it recognizes as C keywords or C 
operations. Generally, the process goes something like this: the compiler grabs a line of source code 
and compares what it finds there to a list of instructions it's able to handle. If it finds a match, it 
writes to the object file it's creating the machine-language code that represents the C instruction it 
found. If it doesn't find a match, it sets aside the instruction and goes on to the next. 

For example, let's say the compiler has just read in this line: 

for (x=0; x<10; ++x) 

This is a standard for/next loop, and the compiler knows exactly what to do with it. The keyword for 
will be in its list of acceptable instructions and the values to use in the loop are found within the 
source line itself. The only stumbling block is the variable x. If x has been defined properly, its address 
will be found in a table of addresses the compiler has built. If x isn't found in the table, the compiler 
will generate an error. 

Now let's say the compiler reads in this line: 

v_bar(handle, pxy); 

The compiler can check for the variables handle and pxy to make sure they're in its table. If they're 
found in the table, the compiler is satisfied. If they're not in the table, an error is generated. But what 
about the label v_bar()? It's a function, not a keyword, so it won't be found in the compiler's list of 
instructions. The compiler has no idea of what to do with v_bar(), so it just assumes that it'll run 
across the label for this function somewhere else in the program. It leaves a space for its address and 
moves on to the next line. 

If v_bar() happened to be one of our own functions, the compiler would come across it sooner or 
later and store its address in the space it reserved for that address. (This is called "back patching," 
and not all compilers do this. Sometimes patching in the address is left to the linker.) But, as you 
know, v_bar() is a VDI function. The function itself will not be found in our source code. Does this 
little problem upset the compiler? Nope. The compiler couldn't care less about the absence of a 
function. It'll just assume that the function we're calling will be found in another module, and pass 
the problem along to the linker. 
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Linking 

It's important to realize that the code produced by the compiler, even though it's in machine- 
language form, is not executable. In that object module are many "references" that need to be 
resolved, such as v_bar() from the above example. Essentially, what the compiler has passed on to 
the linker is an object module containing all the machine code generated from our source code, but 
missing much of the machine-language code it needs to become executable. 

When the compiler came across our call to v_bar(), for instance, it didn't know where the code for 
this mysterious function was -- so it left a blank for the linker to handle. When we link the program, 
the linker will add the code needed to perform v_bar() and patch the address of that code into the 
blank space left by the compiler. 

What is the address of v_bar()? Well, we don't know. All (well, almost all) of the programs that run 
on an ST must be "relocatable" -- that is, they must be able to run anywhere in your ST's memory. 
This causes a problem for the linker when it comes to addresses, because the addresses of functions 
and data will change depending on where the program is loaded in memory. I said the linker must 
supply the addresses, right? How can the linker supply an address for a relocatable program that has 
yet to be loaded in memory? 

In a way, it can't. All the addresses generated during the compile and link process are actually offsets 
from the beginning of the program. The beginning of the program is given the address of zero. When 
you load an executable program into your ST's memory, the program loader replaces these offsets 
with real addresses. It sounds tricky, but there's really nothing to it. All the loader has to do is add the 
offsets already generated during the compile and link to the address the program is being loaded at. 
This sum will be an absolute address. Simple, eh? 

Although we don't know at link time the absolute address of v_bar() (or any other function), we do 
know where the code for calling this function on a machine-language level can be found: it's in 
Megamax's system library, SYSLIB. In fact, SYSLIB contains the code for calling all the GEM and TOS 
functions listed in your Megamax manual. (Other compilers have a similar system library, but its 
name may be different.) 

Notice I said above that SYSLIB contains the code for calling all the functions. The machine-language 
code that actually performs v_bar() and the other system functions are built in to your ST's operating 
system; it's part of GEM. The code found in SYSLIB "binds" the code generated by the compiler to the 
OS routines. This binding is necessary because the ST's operating system requires a lot of special 
handling. For instance, a VDI call needs to have some arrays filled in before it can do its work. When 
programming in C, these arrays are invisible to us. But if we were programming in assembly 
language, we'd have to handle these arrays ourselves. 

So the linker takes the code that was generated by the compiler and attempts to resolve all the 
missing addresses. In its attempt to do this, the linker will search through any other files to which we 
may be linking, as well as its own system files. When the linker finds the proper label in its table, it 
adds the machine code for the function to our already existing object module and patches in the 
address of the code. This continues, with the linker constantly adding code and resolving addresses, 
until it gets to the end of the object code module, at which point, we have a complete program. 

The File Types 

Some people may be confused about all the different file types we encounter when putting together 
a program in C. There are really only three we need to be concerned with: .0, .H files and libraries. 

The .0 files are the object files we've been talking about. They are in machine-code form, but are not 
as yet executable. They need to be combined by the linker with the code that will make them 
complete programs. 
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When developing a program in C, it is advantageous to compile finished portions of the program into 
separate .0 modules. This technique greatly speeds up compile time as our program gets bigger and 
bigger, since the code we've written previously doesn't need to be compiled every time; it just has to 
be linked to our new code. 

Let's write a simple program that will illustrate some of the things we've been talking about. First, 
type in the following code under the filename TEST.C and compile it: 

main () 

{ 

print_text ( "This is a test." ); 
gemdos (Oxl); 

} 

After compilation you should have the file TEST.O on your disk. This file contains the machine-code 
equivalent of the C program shown above. The compiler has converted everything in the source code 
except the call to print_text(). The compiler can't do anything about this function because it doesn't 
know where or what it is. Did the compiler complain? Did you get an error? No. The compiler 
assumed you know what you're doing and left the missing-function problem for the linker to solve. 

Now try to link TEST.O. What happened? After searching through all its libraries in vain, the linker 
told us that it didn't know anything about a function called print_text(). The linker passed the 
problem back to us. We have to solve the problem by writing the code for print_text(). Type the 
following under the filename PRINT.C and compile it: 

print text ( string ) 
char *string; 

{ 

printf ( "%s\n", string ); 

} 


You should now have on your disk the files TEST.O and PRINT.O. All we have to do to get an 
executable program is to link these two files together. Do that now, and then run the resultant 
program. Hurray! It works! 

(Of course, the linker did more than just put together our two object modules; it also added other 
necessary code, such as the printf() routines from the system libraries.) 

Megamax's libraries (SYSLIB, DOUBLE.L, and ACC.L) are really the same thing as .0 files. They each 
contain the object code necessary to perform certain functions. We already talked about SYSLIB; you 
know what it is. The file DOUBLE.L is a machine-language module that, when linked into your 
program, replaces the regular floating point math routines with more accurate ones, allowing you to 
get greater precision (while sacrificing a little on speed). The ACC.L file needs to be linked to your 
program whenever you're writing a desk accessory, since desk accessories have to be initialized 
differently than regular programs. 

Finally, we have the .H files. There is really no mystery here. These "header" files are included with 
your compiler as a convenience. Because there are hundreds and hundreds of standard names for 
various GEM parameters, as well as various standard structures that are used by GEM programmers, 
it would be silly to have to type all that stuff in every time we want to write a program. To save wear 
and tear on our keyboards (as well as our patience), all the commonly used data structures and 
names are provided for us. All we have to do is "include" them into our code. 

We can do the same sort of thing when writing our own programs. To keep down the size of each 
module of our program, we can take all the #defines and global data declarations normally found at 
the top of your program and place them into a separate file. Traditionally, this type of file is given the 
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.H extension. Let's say your main source code file is called MYPROG.C. You would then name the 
header file containing the data mentioned above into a file called MYPROG.H. Then, at the top of 
your program, you would have the line #include MYPROG.H so that the compiler would know where 
the code really belongs. Take a look at the .H files that came with your compiler, and you'll see that 
they are really nothing more than a collection of #defines and data declarations. 

Moving Along 

For some of you, this excursion into the world of compilers and linkers was a rehash of information 
you were already familiar with. If there was nothing here for you, I apologize. But I know that there 
are many of you who have been taking the compilation process for granted, and many of you may 
have run into problems that you couldn't understand because you didn't know what was going on 
with your compiler. I hope this discussion cleared some of the clouds. If nothing else, I'm sure you 
gained some appreciation of what marvelous feats of programming compilers and linkers are. 
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CHAPTER 26 - SIMPLE ANIMATION TECHNIQUES 


Performing animation on the ST is a little bit tougher than it is on the 8-bit Atari computers, if for no 
other reason than the ST does not have player/missile graphics. The programmer is responsible for 
every step of the animation, getting little help from the hardware itself. Even so, coming up with a 
simple animation sequence is not particularly difficult — as long as you are willing to do some 
preliminary work and are competent in handling MFDB's (Memory Form Definition Blocks) and raster 
operations. 

In this chapter, we will study the creation of an animation sequence through each step of the 
process. But we will not review previously covered material; therefore, if you are not comfortable 
with MFDBs and the vro_cpyfm() function, I strongly advise that you review the chapter on raster 
operations. 

The Program 

Once you have the program compiled and linked, go ahead and run it. (Color only.) The screen will go 
blank, after which you should press the left mouse button. A space ship will appear on the right side 
of the screen, and a photon missile will start moving toward it from the left. When the missile 
collides with the ship, the ship will explode, and you'll once again be faced with a blank screen. Either 
press the left button to see the animation again, or the right button to exit back to the desktop. 

The First Step 

Before we program an animation, we must, of course, have something to animate. In other words, 
we must first take out a program like D.E.G.A.S. and draw the various figures that will make up the 
animation sequence. 

For example, if we wanted to have an exploding ship, we would start with the ship itself as frame 
one. Then we would take that ship and add a yellow glow to its center; this would be frame two. For 
frame three, we would expand the yellow glow. Frame four would show the ship completely 
engulfed by the glow, and in the last frame we would have the ship disintegrating into pieces. 

In our sample animation, we also have a photon missile moving across the screen and hitting the 
alien ship, causing it to explode. The photon animation is made up of three frames. 
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EXPLODING SHIP ANIMATION FRAMES 



Frame 4 Frame 5 


Frame 1 


PHOTON ANIMATION FRAMES 



Frame 2 


Frame 3 




Once we have created all the figures we need for the animation, we must convert the graphics into 
numerical data. We do this using a sprite editor, such as Raster Sprite Editor from Issue 16 of ST-Log. 
These editors allow the user to "cut" a section of a picture and convert the cut section into the 
proper form of data. All we must do then is place the data into our program. 

If you look at the top of Listing 1, you will see the graphics data for our sample animation. The data 
labeled alien[] is the alien ship. The data blocks labeled expll[], expl2[], expl3[], and expl4[] are the 
alien ship in its various stages of disintegration. Finally, the blocks of data labeled photonl[], 
photon2[], and photon3[] are the figures for our photon animation sequence. 

Programming the Animation 

Now that we have all our figures converted to data, we must come up with a program that'll move 
that data on and off the screen in such a way as to create the actual animation. In the case of the 
photon, we must copy each figure to the screen in sequence, while at the same time moving the 
photon toward the alien ship. The exploding alien ship will be a little easier to do, since we don't 
have to move the ship itself. 
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Let's take a look at the program listing. First turn your attention to the function main(). Here we 
initialize the application and open a virtual workstation. Then we check the resolution to make sure 
that the user is not trying to run the program in medium or high resolution. If we're in the wrong 
resolution, we bring up an alert box that informs the user of his error, after which we close the 
workstation and exit back to the desktop. If the screen resolution is okay, program execution goes to 
the function do_animate(). In this function, all we really do is monitor the mouse buttons. If the left 
button is pressed, we perform the animation, then come back to wait for another button press. If the 
right button is pressed, we exit the program. 

The Photon 

When the left button is pressed, program execution jumps to the function photonQ, where the actual 
animation begins. In photonQ we first store the address of each image of our photon animation into 
the array of pointers, ph[]. We then turn off the mouse and draw the image of the alien ship on the 
right side of the screen using our own function, draw_icon(). 

Next we initialize the X and Y coordinates of the photons, as well as the color stored in pen. The 
while loop that follows this initialization will repeat until pen is changed to one of the colors that 
make up the alien ship. Within the loop, we draw each stage of the photon animation, moving it 
slightly to the right each time. To animate the photon, we first draw the initial figure in the 
sequence, using draw_icon(). Then, in order to control the speed of the animation, we call the AES 
function, evnt_timer() like this: 

evnt timer( low, high ); 

Here, low is the low word of the number of milliseconds to pause and high is the high word of the 
number of milliseconds to pause. This function always returns a 1. 

After the pause, we redraw the sprite in the same position. Because we are using a writing mode of 
6, which Exclusive ORs the source and destination values, this second drawing of the sprite erases the 
first from the screen, leaving the screen exactly as it was before we drew the sprite. The only 
problem with this method of drawing a sprite over a background is that when the sprite is first 
drawn, it will appear transparent; that is, any graphics behind it will show through. In this case, 
because our display consists of nothing more than a black screen, we experience no problems when 
we Exclusive OR a sprite with the background. 

After erasing the first sprite, we add 4 to x, the sprite's X coordinate, so that the next photon sprite 
will be drawn farther to the right, closer to the alien ship. Then we increment p, so the next time we 
use p to index our array of pointers, ph[], we'll be pointing to the next image in the photon sequence. 
Finally, we get the color of the screen at our current location and call evnt_timer() to pause 50 
milliseconds before going on to the next frame of the animation. 

To retrieve the color of the pixel at our current screen location, we use a call to a VDI function, 
v_get_pixel(): 

v_get_pixel( handle, x, y, Spixel, &pen ); 

Here, handle is the virtual workstation handle, x and y are the X and Y coordinates of the pixel we 
wish to examine, &pixel is the address of an integer that will be set to 1 if the pixel being examined is 
set and set (unset?) to 0 if it's not, and &pen is the address of an integer that will contain the color 
value of the pixel being examined. 

If the color detected is one of the colors that make up our ship (in this case, we're looking for RED or 
DRK_RED), we know that the missile has collided with the ship. We drop out of the loop, after which 
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program execution jumps to the function kill_alien(), where we will perform the exploding-ship 
animation. 

Kaboom! 

Because we don't need to actually move the ship, the explosion sequence is much easier. All we must 
do is draw the four frames of the animation one after the other, providing a short delay between 
them and erasing each image before drawing the next. This time around, we're erasing the images by 
drawing a black circle on top of them, rather than using the Exclusive OR method described above. 

Once the main sequence is completed, we drop into the code that draws the "sparkles" on the 
screen -- just to add a little pizazz. Here we're doing nothing more than using v_pmarker() to draw 40 
crosses in random locations within the area that the ship occupied. Because we're drawing them so 
fast, you would swear that there were many of them on the screen at the same time! When we're 
through in kill_alien(), it's back to photonQ to turn the mouse back on and then back one more step 
to do_animate() to wait for the next mouse button click. A left click will repeat the animation, while a 
right click will exit the program. 

The End Again 

As you can see, simple animation on the ST is not difficult. However, be aware that, unlike its 8-bit 
little brother, the ST is not well designed for animations involving many objects at once. The lack of 
player/missile graphics makes programming arcade-type action games a real chore. And there's 
really no way to do it in C; you have to have the speed of assembly language. Still, the techniques 
presented here can be effective and fun in simple applications. Experiment a bit, and see what you 
come up with. You might surprise yourself. 
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Program Listing #1 

j •k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k 

*C-manship, Listing 1 
*CHAPTER 2 6 

*Developed with Laser C 

•k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k-k-k-k-k-k-k'k-k'k-k-k-k-k-k-k-k'k-k'k-k-k-k-k-k^ 

#include <stdio.h> 

#include <osbind.h> 


#define BLACKO 
#define RED2 
#define WHITE8 
#define DRK_RED9 
#define TRUE 1 
#define FALSEO 
#define NONE 0 
#define LEFT 1 
#define RIGHT2 
#define LOWO 
#define REPLACE1 
#define DOT2 
#define M OFF256 
#define M ON 257 


/* GEM arrays */ 

int work in[ll], work-out[57], contrl[12], intin[128], 
ptsin[128], intout[128], ptsout[128]; 


int desk_palette[16]; /* Desktop color palette. */ 

/* Our own color palette. */ 

int my_palette[16] = { 0x000,0x700,0x060,0x770, 

0x007,0x707,0x333,0x666, 
0x400,0x444,0x373,0x773, 
0x337,0x003,0x377,0x400 }; 


int handle,/* GEM graphics handle */ 

dum; /* A dummy variable for storage of values */ 


/* Data for sprites. */ 
long alien[] = { 

0x00000000,0x00000000,0x10000000,0x00000800, 
0x00000000,0x00000000,0x20000000,0x00000400, 
0x00000000,0x00000000,0x60000000,0x00000600, 
0x00000000,0x00000000,0x78000000,0x00000600, 
0x00000000,0x00000000,0x00000000,0x00003C00, 
0x00000000,0x00000000,0x30000000,0X00000C00, 
0x00000000,0x00000000,0x30000000,0X00004E00, 
0x00000000,0x00000000,0x42000000,0x00002400, 
0x00020000,0x00000000,0x83400040,0x00404040, 
0x00030000,0x00000000,0x01C00040,0x0040 8040, 
0x00030000,0x00000000,0x00800000,0x00000040}; 
int alien w = 32, alien h = 10; 


long expll[] = { 

0x00000000,0x00000000,0x00000000,0x00000000, 
0x00000000,0x00000000,OxlEOOOOOO,0x00000000, 
0x00000000,0x00000000,0x3F000C00,0X00000C00, 
0x00000000,0x00000000,0x3F000000,0x00000000, 
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0x00000000,0x00000000,OxlEOOOCOO,OxOOOOOCOO, 
0x00000000,0x00000000,0X1E000C00,0X00000C00, 
0x00000000,0x00000000,0X3F000C00,0x00000000, 
0x00000000,0x00000000,0x3F000C00,OxOOOOOCOO, 
0x00000000,0x00000000,0x61800000,0x00000000, 
0x00010000,0x00000000,0XC0E00000,0x00000000, 
0x00010000,0x00000000,0XC0E00000,0x00000000 } ; 

int expl w = 32, expl h= 10; 

long expl2[] = { 

0x00000000,0x00000000,0x18000000,0x00000000, 
0x00000000,0x00000000,0x3C000000,0x00000000, 
0x00000000,0x00000000,0x7E001800,0x00001800, 
0x00000000,0x00000000,0x7E001800,0x00001800, 
0x00000000,0x00000000,0x3C003800,0x00003800, 
0x00000000,0x00000000,0x3C001800,0x00001800, 
0x00000000,0x00000000,0x7E001800,0x00001000, 
0x00000000,0x00000000,0x3C001800,0x00001800, 
0x00000000,0x00000000,0xFF003C00,0x00003C00, 
0x00030000,0x00000000,0x81C00000,0x00000000, 
0x00030000,0x00000000,0x81C00000,0x00000000}; 

long expl3[] = { 

0x003C0018,0x00000018,0x00000000,0x00000000, 
0x007E003C,0x0000003C,0x00000000,0x00000000, 
0x007E003C,0x0000003C,0x00000000,0x00000000, 
0x013D0019,0x00000019,0x00000000,0x00000000, 
0x07BD0799,0x00000799,0x00000000,0x00000000, 
0x03FF0199,0x00000181,0x80000000,0x00000000, 
OxOlFFOlFF,OxOOOOOlFF,OxCOOOCOOO,0x00000000, 
0x00FF006D,0x0000006D,0x00000000,0x00000000, 
0x03B90038,0x00000038,OxCOOOOOOO, 0x00000000, 
0x03AD002C,0x0000002C,0xC0000000,0x00000000, 
0x00260026,0x00000026,0x00000000,0x00000000}; 

long expl4[] = { 

0x01350004,0x00000000,0x00000000,0x00000000, 
0x02CA0282,0x000000 82,0x00000000,0x00000000, 
0x01340010,0x00000000,0x80000000,0x00000000, 
0x04B500Bl, 0x00000031,0x00000000,0x00000000, 
OxOBAAOBOO,OxOOOOOAOO, 0x8000 8000,0x00000000, 
0x06190210,0x00000210,0x40000000,0x00000000, 
OxOOFCOOBO,0x00000000,0x80008000,0x00000000, 
0x04A604A0,OxOOOOOOAO, 0x00000000,0x00000000, 
0x01490009,0x00000000,0x00000000,0x00000000, 
0x07330020,0x00000020,0x80000000,0x00000000, 
0x07030000,0x00000000,0x80000000,0x00000000}; 


long photonl[] = { 

0x00000000,0x00000000,OxOOCOOOOO,0x00000000, 
0x00000000,0x00000000,OxOOCOOOOO, 0x00000000, 
0x00000000,0x00000000,OxOOCOOOOO, 0x00000000, 
0x00000000,0x00000000,OxOOCOOOOO,0x00000000, 
0x00000000,0x00000000,0x00800000,0x00000340, 
0x00000000,0x00000000,0x00800000,0x00000760, 
0x00000000,0x00000000,0x01800000,0x00000E70, 
0x00000000,0x00000000,0X03C00080,0x00000C30, 
0x00000000,0x00000000,OxFFCOOlOO,0x00000030, 
0x00000000,0x00000000,OxOlFOOlOO,OxOOOOOEOO, 
0x00000000,0x00000000,0x023C0000,0x000005C0, 
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0x00000000,0x00000000,0x041F0000,0x000003C0, 
0x00000000,0x00000000,0x080F0000,0x00000000, 
0x00000000,0x00000000,0x00070000,0x00000000, 
0x00000000,0x00000000,0x00020000,0x00000000, 
0x00000000,0x00000000,0x00000000,0x00000000}; 
int photon h = 15, photon w = 32; 


long photon2[] = { 

0x00000000,0x00000000,0x20000000,0x00000000, 
0x00000000,0x00000000,0x60000000,0x00000000, 
0x00000000,0x00000000,0x30000000,0x00000000, 
0x00000000,0x00000000,0x18040000,0x00000000, 
0x00000000,0x00000000,OxOCO80000,0x000003C0, 
0x00000000,0x00000000,0x04100000,0x000003E0, 
0x00000000,0x00000000,0x03E00100, OxOOOOOCIO, 
0x00000000,0x00000000,0x03C00080,0x00000C30, 
0x00000000,0x00000000,0X03C00100,0x00000C30, 
0x00000000,0x00000000,0x01800000,0x00000E70, 
0x00000000,0x00000000,0x01000000,0x000006E0, 
0x00000000,0x00000000,0x01000000,0x000002C0, 
0x00000000,0x00000000,0x03000000,0x00000000, 
0x00000000,0x00000000,0x03000000,0x00000000, 
0x00000000,0x00000000,0x03000000,0x00000000, 
0x00000000,0x00000000,0x03000000,0x00000000}; 

long photon3[] = { 

0x00000000,0x00000000,0x60000000,0x00000000, 
0x00000000,0x00000000,0x30200000,0x00000000, 
0x00000000,0x00000000,0xl8200000,0x000003C0, 
0x00000000,0x00000000,0x00400000,0x000003A0, 
0x00000000,0x00000000,0x03800000,0x00000070, 
0x00000000,0x00000000,0x03000100,0x00000030, 
0x00000000,0x00000000,0x03FF0040,0x00000000, 
0x00000000,0x00000000,0x03800080,0x00000070, 
0x00000000,0x00000000,0x06000000,0x000001E0, 
0x00000000,0x00000000,0x10000000,0x000003C0, 
0x00000000,0x00000000,0x78000000,0x00000000, 
0x00000000,0x00000000,0XF0000000,0x00000000, 
0x00000000,0x00000000,0x60000000,0x00000000, 
0x00000000,0x00000000,0x00000000,0x00000000, 
0x00000000,0x00000000,0x00000000,0x00000000, 
0x00000000,0x00000000,0x00000000,0x00000000}; 


typedef struct fdbstr 
{ 

longfd_addr; 
int fd_w; 
int fd h; 
int fd_wdwidth; 
int fd_stand; 
int fd nplanes; 
int fd_rl; 
int fd_r2; 
int fd_r3; 

} MFDB; 

/kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* Main program. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

main () 
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{ 

appl_init (); 

open vwork (); 

if ( Getrez () != LOW ) 

form alert ( 1, "[1][This demo must be run|in low \ 

resolution][OK]" ); 

else { 

do_animate (); 

Setpalette ( desk_palette ); 

} 

v_clsvwk ( handle ); 
appl_exit (); 

} 

/■k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k-k'k-k'k-k'k-k'k-k'k'k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k 

* do_animate () 

~k 

* Main program loop. Reads the mouse buttons and goes to 

* the appropriate functions based on the button presses. 

•k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k-k'k-k'kic'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k/ 

do_animate () 

{ 

int repeat, button, x, y; 

setcolors (); 
repeat = TRUE; 
while ( repeat ) { 

button = 0; 

while ( button == NONE ) 

vq_mouse ( handle, Sbutton, &x, &y ); 
if ( button == LEFT ) 
photon (); 

else if ( button == RIGHT ) 
repeat = FALSE; 

} 

} 

j •k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k 

* photon () 

~k 

* Performs the photon animation. The function checks for 

* a "hit" by getting the color of the screen from the 

* current photon position and comparing it to the alien 

* ship's color. 

-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k/ 

photon () 

{ 

int x, y, pixel, pen, p; 
long *ph[3]; 

p = 0; 

ph[0] = photonl; 
ph[l] = photon2; 
ph[2] = photon3; 
graf mouse ( M_OFF, OL ); 

draw_icon ( alien, 7, 250, 100, alien_w, alien h ); 
x = 20; 
y = 100; 
pen = BLACK; 
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while ( pen!=RED && pen!=DRK RED ) { 


draw icon ( 

ph[p], 

6, 

x-6. 

y-6. 

photon w, photon h ) ; 

evnt timer ( 

O 

o 
\ —1 

) ; 




draw icon ( 
x += 4; 

ph[p], 

6, 

x-6. 

y-6. 

photon w, photon h ) ; 

if ( ( p+=l 

) > 2 ) 

! 




p = 0; 






v get pixel 

( handle. 

x+19, 

y+4 

, Spixel, &pen ); 


evnt_timer ( 50, 0 ); 

} 

kill alien (); 
graf_mouse ( M_0N, 0L ); 


/■k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k 

* kill^alien () 

* Performs the exploding ship animation. 

'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k'k-k'k-k'k-k'k-k'k-k'k-k'k'k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k/ 

kill alien () 

{ 

int x, y, rx, ry, i; 
int pxy[2]; 

x = 250; 
y = 100; 


vsf color ( 

handle. 

BLACK ); 


draw icon ( 

expll, 

7, x, y, expl w, expl h ); 

evnt timer 

( 50, 0 

) ; 


v circle ( 

handle. 

x+20, y+7. 

10 ) ; 

draw icon ( 

expl2, 

7, x+1, y. 

expl w, expl h ); 

evnt timer 

( 50, 0 

) ; 


v circle ( 

handle. 

x+20, y+7. 

10 ) ; 

draw icon ( 

expl3, 

7, x+7, y. 

expl w, expl h ); 

evnt timer 

( 50, 0 

) ; 


v circle ( 

handle. 

x+20, y+7. 

10 ) ; 

draw icon ( 

expl4, 

7, x+7, y. 

expl w, expl h ); 

evnt timer 

( 50, 0 

) ; 


v circle ( 

handle. 

x+20, y+7. 

10 ) ; 

x += 13; 
y -= 4; 
vsm type ( 

handle. 

DOT ) ; 


vsm height 

( handle 

, i ); 


for ( i=0; 

i<40; ++i ) { 


rx = 

rnd ( 16 

) ; 


ry = 

rnd ( 16 

) ; 


pxy [0 

] = x + 

rx; 


pxy [1 

+ 

>i 

II 

ry; 



vsm^color ( handle, WHITE ); 
v_pmarker ( handle, 1, pxy ); 
evnt_timer ( 10, 0 ); 

vsm^color ( handle, BLACK ); 
v_pmarker ( handle, 1, pxy ); 

} 

} 


! ■k-k'k-k-k-k'k-k-k-k'k-k-k-k'k-k'k'k-k'k-k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k-k'k-k-k-k'k-k'k-k'k-k-k-k'k'k-k-k'k-k'k-k 
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* draw icon () 

k 

* A general function for drawing icons. It may be used 

* in other programs as long as the header file GEMDEFS.H 

* has been included at the top of the program. The input 

* to the function is the address of the icon's data, the 

* desired drawing mode, the X and Y coords at which the 

* icon should be drawn, and the width and height of the 

* icon. For low resolution only. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk/ 

draw icon ( data, mode, dx, dy, width, height ) 
long data; 

int mode, dx, dy, width, height; 

{ 

MFDB s m, scr^m; 
int pxy[8]; 

s_m.fd addr = data; 

s_m.fd_w = width; 

s_m.fd h = height; 

s_m.fd wdwidth = width / 16; 

s_m.fd_stand = 0; 

s_m.fd nplanes = 4; 

scr_m.fd_addr = 0; 

pxy[0] = 0; 

pxy[1] = 0; 

pxy[2] = width; 

pxy[3] = height; 

pxy[4] = dx; 

pxy[5] = dy; 

pxy[6] = dx + width; 

pxy[7] = dy + height; 

vro cpyfm ( handle, mode, pxy, &s_m, Sscr^m ); 

} 

j ■kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* set_colors () 

* This function stores the original desktop colors, and 

* then installs the program's palette. 

-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k/ 

set_colors () 

{ 

int x; 

graf^mouse ( M_OFF, 0L ); 

for ( x=0; x<16; desk_palette [x++] = Setcolor ( x, -1 ) ); 

v_clrwk ( handle ); 

Setpalette ( my_palette ); 
graf_mouse ( M_ON, 0L ); 

} 

Jkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk 

* open vwork () 

k 

* This function opens a virtual work station. 

kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkj 

open vwork () 

{ 
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int i; 

handle = graf_handle ( &dum, &dum, &dum, &dum ); 
for ( i=0; i<10; work in[i++] = 1 ); 
work in[10] = 2; 

v_opnvwk ( work in, Shandle, work-out ); 

} 

j •k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k 

* rnd () 

* This function is used to get a random number from 0 to 

* n-1. Its input is "n" and its output is the random number. 

•k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k'kj 

rnd ( n ) 
int n; 

{ 

int r; 

r = ( int ) Random (); 
r = abs ( r ) % n; 

return ( r ); 
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CHAPTER 27 - A COMPLETE GEM APPLICATION - PART 1 


NOW COMES THE TIME when we apply everything we've learned to a full-length GEM program. In 
the next few chapters, we're going to be digging deep into MicroCheck ST, a home finance system 
written by your humble author, to see how a complete GEM application is put together. In order to 
understand these discussions, you will need a good background in GEM programming. I won't be 
reviewing topics extensively, but rather will be pointing out the ways in which the techniques we've 
studied are put to use in this program. 

Warning: The discussions that follow, in this chapter and the ones coming up, are not exactly what 
might be called easy reading. Essentially, I'll be documenting a large section of the MicroCheck ST 
source code in function-by-function fashion. My goal is to tell you as quickly as possible what each 
function does. Put simply, the reading from here on is as dry as the Sahara at noon. 

The Listings 

Listing 1 is the header file — created by the Resource Construction Set -- for MicroCheck ST. Listing 2 
is the first portion of the source code. In order for these listings to run properly, you need to have the 
file MICROCHK.RSC, which can be found, along with the complete MicroCheck ST source code, on the 
optional disks for this book. Those of you who don't want to buy the disk version can use Listing 3 
to produce the MICROCHK.RSC file. Simply type it into ST BASIC and run it. 

The portions of MicroCheck ST included here in Listings 1 and 2 will compile and link with no 
problems, even though they are only a small portion of the full program. Be forewarned, however, 
that when you run the program created from these listings, the only way to get back to the Desktop 
is to reboot your computer. The portion of MicroCheck ST that includes the "Quit" function is not 
presented this chapter. 

Getting Down To It 

As I said above, Listing 1 is a file that was created by the Resource Construction Set. It contains 
nothing more than a series of #defines that equate the object and tree ID numbers of our resource 
with names that are easier to remember and that make for better-reading code. There's not much to 
say about this listing, except that you'll see every name there used somewhere in the MicroCheck ST 
source code (though not necessarily in the portion being presented this chapter). 

Listing 2 is a small section of the MicroCheck ST source code. It is only about 1/8 of the full program, 
which gives you some idea of how large a full-GEM application may be. Although GEM is a great boon 
to the end user, whatever conveniences he gets are passed on to the programmer as extra work. A 
large portion of a GEM program deals with handling GEM rather than getting down to the business of 
the application itself. Setting up and handling dialog boxes, windows and menu bars takes many lines 
of code. 

At the very top of the listing we have some #includes, which tell the compiler to add these files into 
our program at compilation time. We've discussed these files before. Note that the MICROCHK.H file 
is also included here. 

Below the #includes we define some constants of our own. As we saw with the MICROCHK.H file, any 
time we can replace a number, which tends to be cryptic, with a name, we'll be making our 
programming task easier and our resultant code more readable. Which makes more sense to you: 
OxleOl or CNTL_A? 

Below that we have the usual GEM global arrays. Every GEM application has to provide these storage 
areas. 
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Next we declare some of our own variables. The array msg_buf[] will be used to store messages sent 
to us by GEM. The array pwrs[] is used in a conversion function not shown in this chapter's listing. 
There's also a long list of integers and character arrays. I won't spend a lot of time now explaining 
what each one is. We'll talk about them as they appear in the listings. If you look through the list of 
integers being declared, though, you'll see a lot of variable names you've run across before — 
variables that are needed to handle GEM's many functions. 

Take a look at the pointers of type OBJECT declared below the character strings. If you've been 
keeping up with your studies, you'll know that these pointers will contain the addresses of each of 
the trees that make up our full resource tree. 

A little farther down, you'll see a structure named check. This structure has storage areas for each 
piece of data we need for a checking account transaction: the check number, the payee, a memo 
field, the date the check was written, the amount of the check, and a field to indicate if the check has 
been cancelled (processed by the bank). 

Of course, a checking program that'll hold enough data for only one check is useless. That's why our 
next step in setting up our data is to create an array of these structures — the arrays named checks[] 
and srch_checks. The former will hold all the transactions for a particular month, and the latter will 
hold all the transactions that match the search criterion when a search of the account is performed. 
The pointer, *cur_chk_strc, will be used to keep track of which of the two check structures we're 
currently using. 

Finally, the last item declared before the program begins is the pointer *ob_tedinfo, which is a 
pointer to a TEDINFO structure. Hopefully, you'll remember that a TEDINFO structure is used to hold 
the information we need for an editable text field in a dialog box. 

Function mainQ 

Every program is made up of three main sections: initialization, the program proper, and the job-end 
section (clean-up). Our function main() breaks these three sections into six easy-to-follow steps. The 
functions appl_init() and open_vwork() initialize our GEM application (not the program, mind you, 
just GEM). The function do_mcheck() is the controlling function for MicroCheck ST — where main() 
handles the three sections of setting up the GEM operating system, do_mcheck() does the same for 
our actual program. Finally, the functions v_clsvwk(), SetcolorQ, and appl_exit() perform the job-end 
duties, closing down our workstation and returning the GEM desktop to the same condition it was 
when we left it. 

Function do_mcheckQ 

The function do_mcheck() begins by setting the ST's colors the way we want them and checking to 
see if the user has run the program in the proper resolution. If the resolution is okay, we set the 
mouse to an arrow and initialize some strings and variables. Then we get the system date with a call 
to the function get_date(). 

The next step in our program initialization is to load the resource file and get the addresses of each 
of the trees that make up the resource. First, we check to see that the file MICROCHK.RSC is on the 
disk.(It must be in the same directory as the main program.) If it's not, we warn the user of the error 
and return to the Desktop. If the resource file is available, we load it and get the addresses of each of 
the trees. Remember that each of these trees makes up one of the GEM forms — such as a dialog box 
or menu bar -- that we will be using to get data to and from the user. 

After we load the resource file, we bring up the menu bar with a call to menu_bar() and set the 
entries in the menus to their active or inactive state with a call to set_menu_entries(). 

Now all we must do is set up our windows, and we're all set. MicroCheck ST actually uses two 
windows, although only one of them is visible. The "invisible" window has no parts (sliders, arrows, 
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etc.) and covers the entire screen area. I use it to get redraw messages for portions of the screen that 
are not covered by the visible window. 

After we set up the windows, we send program execution to the function get_event(), which routes 
the events our application gets from the user to the proper sections of the program. 

Eventually, the user will indicate that he wishes to quit the program. When he does, the last portion 
of do_mcheck() removes the menu bar, closes and deletes the two windows, and releases the 
memory used by our resource tree. 

Function get_eventQ 

As you should already know, a GEM application program receives its instructions from the user by 
way of "events." There are many types of events, handling not only GEM constructions such as 
windows, menu bars, and dialog boxes, but also the mouse and the keyboard. MicroCheck ST is 
interested in three main types of events: keyboard, mouse and GEM message events. 

If you look at get_event() in Listing 2, you'll see that it takes only a small amount of source code to 
retrieve and route the events. Basically, all we must do is get the event, figure out what type it is and 
pass it on. 

To get the events, we use the unwieldy and complicated evnt_multi(). The integer event will hold the 
event number, which we'll test in three different if statements, each of which will route its event to 
the proper function. 

The three functions, handle_keys(), handle_messages(), and handle_button(), process keyboard, 
message, and mouse-button events, respectively. Notice that, at the end of Listing 1, these functions 
are represented by "stubs"; that is, functions that do nothing except provide a label for the linker. 
Without these stubs, you would not be able to link the program successfully. (The actual functions 
will be presented in Chapter 28.) 

Function set_menu_entries() 

The function set_menu_entries() in Listing 1 disables any entries in the menu bar to which we don't 
want the user to have access. For example, until an account has been loaded, it's not possible to 
perform a search on the checks in the account. Rather than giving the user an error message when 
he clicks on the "Search" option, we make the option unavailable to him. The function 
set_menu_entries() is only one of three functions in MicroCheck ST that enable and disable menu 
options based on the program's current mode. 

Functions calc_vslidO and calc_hslidO 

The functions calc_vslid() and calc_hslid() set the sizes and positions of the window's vertical and 
horizontal sliders. This can be a confusing process, but one that is essential to the proper handling of 
windows. Assuming you understand how the sliders work, the only thing worth noting in these 
functions is found in calc_hslid(), where the flag left is used to determine the position of the 
horizontal slider. This method is used because this slider, due to my program design, can be in only 
one of two positions -- all the way to the left or all the way to the right. 

Function open_vwork() 

Now we come to a familiar function, open_vwork(). Anyone who doesn't know that this function sets 
up a virtual workstation, a necessity for a GEM application, should do some heavy reviewing. 
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Function get_date() 

Finally, get_date(), the last function covered in this chapter, is responsible for retrieving and 
formatting the date from the ST's clock. In this function, we're setting up two date strings, date_but[] 
and cur_date(). The former will be in the format mm/dd/yy and will be displayed in a date button at 
the bottom of the screen. The latter will be in the format mmddyy and will be used as the default 
date for the check-entry dialog box. 

Final Notes 

When you run this chapter's segment of MicroCheck ST, you'll find on the screen a half-working 
menu bar and a window with a blank work area. In addition, the information buttons that are 
normally displayed at the bottom of the screen will be missing. This is normal. This portion of the 
program is not yet able to process GEM message events, which trigger the drawing of these screen 
display elements. 

In closing, I would strongly urge those of you who wish to follow this in-depth look at a GEM 
application program to purchase C-manship's optional disks. The complete MicroCheck ST is included 
on the disks. I believe you will better understand our discussions if you're familiar with the program. I 
will, however, try to make these last few chapters as "free standing" as possible, so that those who 
do not wish to purchase the disk can follow along. 

Program Listing #1 


#define 

NEWADIAL 0 


/* TREE */ 




#define 

MENUBAR 1 

/* 

TREE */ 




#define 

FILEDIAL 2 


/* TREE */ 




#define 

DATEDIAL 3 


/* TREE */ 




#define 

SRCHDIAL 4 


/* TREE */ 




#define 

NEWOK 8 


/* OBJECT in 

TREE 

#0 

*/ 

#define 

NEWCANCL 9 


/* OBJECT in 

TREE 

#0 

*/ 

#define 

ABOUT 10 

/* 

OBJECT in TREE 

#1 */ 



#define 

NEWACCNT 19 


/* OBJECT in 

TREE 

#1 

*/ 

#define 

OPENMBR 20 


/* OBJECT in 

TREE 

#1 

*/ 

#define 

CLOSEMBR 21 


/* OBJECT in 

TREE 

#1 

*/ 

#define 

QUIT 23 


/* OBJECT in 

TREE 

#1 

*/ 

#define 

ENTER 26 

/* 

OBJECT in TREE 

#1 */ 



#define 

SEARCH 27 

/* 

OBJECT in TREE 

#1 */ 



#define 

RECONCIL 28 


/* OBJECT in 

TREE 

#1 

*/ 

#define 

PRNTWIND 32 


/* OBJECT in 

TREE 

#1 

*/ 

#define 

PRNTREG 33 


/* OBJECT in 

TREE 

#1 

*/ 

#define 

NEWYEAR 35 


/* OBJECT in 

TREE 

#1 

*/ 

#define 

NEWDATE 36 


/* OBJECT in 

TREE 

#1 

*/ 

#define 

DESK 3 


/* OBJECT in 

TREE 

#1 

*/ 

#define 

FILEBAR 4 

/* 

OBJECT in TREE 

#1 */ 



#define 

CHECKS 5 

/* 

OBJECT in TREE 

#1 */ 



#define 

PRINT 6 


/* OBJECT in 

TREE 

#1 

*/ 

#define 

UTILITY 7 

/* 

OBJECT in TREE 

#1 */ 



#define 

FILENAME 3 


/* OBJECT in 

TREE 

#2 

*/ 

#define 

FILEOK 1 

/* 

OBJECT in TREE 

#2 */ 



#define 

FILECANC 2 


/* OBJECT in 

TREE 

#2 

*/ 

#define 

NWDATE 2 

/* 

OBJECT in TREE 

#3 */ 



#define 

DATEOK 3 

/* 

OBJECT in TREE 

#3 */ 



#define 

DATECANC 4 


/* OBJECT in 

TREE 

#3 

*/ 

#define 

SRCHOK 5 

/* 

OBJECT in TREE 

#4 */ 



#define 

SRCHCNCL 4 


/* OBJECT in 

TREE 

#4 

*/ 

#define 

NEWNAME 2 

/* 

OBJECT in TREE 

#0 */ 



#define 

NEWADDR 3 

/* 

OBJECT in TREE 

#0 */ 



#define 

NEWCITY 4 

/* 

OBJECT in TREE 

#0 */ 



#define 

NEWSTATE 5 


/* OBJECT in 

TREE 

#0 

*/ 
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#define 

NEWZIP 6 

/* 

OBJECT in TREE 

#0 */ 



#define 

NEWBALNC 7 


/* OBJECT in 

TREE 

#0 

*/ 

#define 

MNTHFROM 7 


/* OBJECT in 

TREE 

#4 

*/ 

#define 

MNTHTO 8 

/* 

OBJECT in TREE 

#4 */ 



#define 

NUMFROM 9 

/* 

OBJECT in TREE 

#4 */ 



#define 

NUMTO 10 

/* 

OBJECT in TREE 

#4 */ 



#define 

AMNTFROM 11 


/* OBJECT in 

TREE 

#4 

*/ 

#define 

AMNTTO 12 

/* 

OBJECT in TREE 

#4 */ 



#define 

PAYEFROM 13 


/* OBJECT in 

TREE 

#4 

*/ 

#define 

MEMOFROM 14 


/* OBJECT in 

TREE 

#4 

*/ 

#define 

CHKCAN 29 

/* 

OBJECT in TREE 

#1 */ 



#define 

CANCDIAL 5 


/* TREE */ 




#define 

CANCOK 3 

/* 

OBJECT in TREE 

#5 */ 



#define 

CANCCANC 4 


/* OBJECT in 

TREE 

#5 

*/ 

#define 

JAN 6 


/* OBJECT in 

TREE 

#5 

*/ 

#define 

FEB 7 


/* OBJECT in 

TREE 

#5 

*/ 

#define 

MAR 8 


/* OBJECT in 

TREE 

#5 

*/ 

#define 

APR 9 


/* OBJECT in 

TREE 

#5 

*/ 

#define 

MAY 10 


/* OBJECT in 

TREE 

#5 

*/ 

#define 

JUN 11 


/* OBJECT in 

TREE 

#5 

*/ 

#define 

JUL 12 


/* OBJECT in 

TREE 

#5 

*/ 

#define 

AUG 13 


/* OBJECT in 

TREE 

#5 

*/ 

#define 

SEP 14 


/* OBJECT in 

TREE 

#5 

*/ 

#define 

OCT 15 


/* OBJECT in 

TREE 

#5 

*/ 

#define 

NOV 16 


/* OBJECT in 

TREE 

#5 

*/ 

#define 

DEC 17 


/* OBJECT in 

TREE 

#5 

*/ 

#define 

RECNDIAL 6 


/* TREE */ 




#define 

ENDBAL 2 

/* 

OBJECT in TREE 

#6 */ 



#define 

ENDBOK 3 

/* 

OBJECT in TREE 

#6 */ 



#define 

ENDBCANC 4 


/* OBJECT in 

TREE 

#6 

*/ 

#define 

CANCSTRG 1 


/* OBJECT in 

TREE 

#5 

*/ 

#define 

MZERO 18 

/* 

OBJECT in TREE 

#5 */ 



#define 

CHEKDIAL 7 


/* TREE */ 




#define 

CHKNAME 1 

/* 

OBJECT in TREE 

#7 */ 



#define 

CHKSTREE 2 


/* OBJECT in 

TREE 

#7 

*/ 

#define 

CHKCITY 3 

/* 

OBJECT in TREE 

#7 */ 



#define 

DATE 5 


/* OBJECT in 

TREE 

#7 

*/ 

#define 

NUMBER 4 

/* 

OBJECT in TREE 

#7 */ 



#define 

PAYEE 6 


/* OBJECT in 

TREE 

#7 

*/ 

#define 

MEMO 8 


/* OBJECT in 

TREE 

#7 

*/ 

#define 

CHKDONE 10 


/* OBJECT in 

TREE 

#7 

*/ 

#define 

CHKNEXT 9 

/* 

OBJECT in TREE 

#7 */ 



#define 

AMOUNT 7 

/* 

OBJECT in TREE 

#7 */ 



#define 

CHKCANCL 11 


/* OBJECT in 

TREE 

#7 

*/ 

#define 

RPRTDIAL 8 


/* TREE */ 




#define 

RECENDB 3 

/* 

OBJECT in TREE 

#8 */ 



#define 

RECSUBT 8 

/* 

OBJECT in TREE 

#8 */ 



#define 

RECCHKS 5 

/* 

OBJECT in TREE 

#8 */ 



#define 

RECDEPS 10 


/* OBJECT in 

TREE 

#8 

*/ 

#define 

RECBALSH 13 


/* OBJECT in 

TREE 

#8 

*/ 

#define 

RECOUTCH 4 


/* OBJECT in 

TREE 

#8 

*/ 

#define 

RECOUTDP 9 


/* OBJECT in 

TREE 

#8 

*/ 

#define 

RECBALIS 15 


/* OBJECT in 

TREE 

#8 

*/ 

#define 

RECDIF 18 

/* 

OBJECT in TREE 

#8 */ 



#define 

RECOK 19 

/* 

OBJECT in TREE 

#8 */ 



#define 

LKMNDIAL 9 


/* TREE */ 




#define 

SCANMNTH 2 


/* OBJECT in 

TREE 

#9 

*/ 

#define 

CHKAUTO 30 


/* OBJECT in 

TREE 

#1 

*/ 

#define 

NEWMNTH 24 


/* OBJECT in 

TREE 

#1 

*/ 

#define 

PAID 12 


/* OBJECT in 

TREE 

#7 

*/ 

#define 

IMPORT 37 

/* 

OBJECT in TREE 

#1 */ 
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#define SRTODIAL 10 

#define DBCNT 3 

#define DBTOT 5 

#define CRCNT 7 

#define CRTOT 9 

#define SRTOOK 10 /* 


/* TREE */ 

/* OBJECT in TREE #10 */ 
/* OBJECT in TREE #10 */ 
/* OBJECT in TREE #10 */ 
/* OBJECT in TREE #10 */ 
OBJECT in TREE #10 */ 


Program Listing #2 

j ■k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k-k-k-k'k-k-k-k'k-k-k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k'k-k 

* MICROCHECK ST 

* by Clayton Walnum 

~k 

* Copyright 1989 by ST-LOG 

* Developed with Laser C 

■k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k-k'k-k-k-k-k-k-k-k'k-k-k-k'k-k-k-k-k-k-k-k-k-k-k-k'k-k-k/ 


#include <stdio.h> 
#include <osbind.h> 
#include <gemdefs.h> 
#include <obdefs.h> 
#include <fcntl.h> 
#include "microchk.h" 


#define WA_UPPAGE 0 
#define WA_DNPAGE 1 
#define WA_UPLINE 2 
#define WA_DNLINE 3 
#define WA_LFPAGE 4 
#define WA_RTPAGE 5 
#define BOLD 1 
#define LIGHT 2 
#define TRUE 1 
#define FALSE 0 
#define YES 1 
#define NO 2 


#define LEFT_BUTTON 0x0001 
#define BUTTON_DOWN 0x0001 
#define NUM_CLICKS 2 
#define PARTS 

NAME|INFO|UPARROW|DNARROW|VSLIDE|FULLER|CLOSER|HSLIDE 


#define 

NUM COLUMNS 

93 

#define 

MED 

1 

#define 

MATCH 

0 

#define 

REC LENGTH 

117 

#define 

FROM BEG 

0 

#define 

FROM CUR POS 

1 

#define 

FAILED 

(-1) 

#define 

DFLT DRV 

0 

#define 

VISIBLE 

1 

#define 

MEDIUM 

1 

#define 

HIGH 

2 

#define 

CHAR AVAIL 

-1 

#define 

CONSOLE 

2 

#define 

ESCAPE 

27 

#define 

CNTL A 

OxleOl 

#define 

CNTL B 

0x3002 

#define 

CNTL C 

0x2e03 

#define 

CNTL D 

0x2004 

#define 

CNTL E 

0x1205 

#define 

CNTL G 

0x2207 
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#define CNTL^I 
#define CNTL_M 
#define CNTL_N 
#define CNTLJD 
#define CNTL_P 
#define CNTL_Q 
#define CNTL_R 
#define CNTL_S 
#define CNTL_W 
#define CNTL Y 


0x1709 
0x320d 
0x310e 
0xl80f 
0x1910 
0x1011 
0x1312 
Oxlf13 
0x1117 
0x1519 


int work in[ll], work-out[57], contrl[12], 

intin[128], ptsin[128], intout[128], ptsout[128]; 


int msg_buf[8]; 

long pwrs[] = { 1, 10, 100, 1000, 10000, 100000, 1000000, 
10000000 }; 

int handle, dum, file, key, 

fullx, fully, fullw, fullh, wrkx, wrky, wrkw, wrkh, 
w hi, w h2, res, full, num trans, charw, charh, curchknum, 
num deps, num_chks, loaded, all_done, mouse x, mouse^y, 
num clicks, edit top, left, start mnth, end mnth, mnth, 
srch trans, start num, end num, cur count, cur top, 
search, saved, canceling, month, full_draw, oldcolr; 

int zero = 0; 


char filename[64], chkname[30], chkstreet[30], chkcity[50], 
date_but[10], bal_but[10], trans_but[4], 
check_but[4], dep_but[4], mnth_but[10], acct_name[64], 
monthfile[64], cur_chk_num[6], cur_date[7], future^use[40], 
cancmnth[5], chtot[20], dptot[20], chcnt[10], dpcnt[10]; 

char windname[64]; 

char noacct[] = "No account opened"; 

char canc[] = "CANCEL CHECKS"; 
char newm[] = " NEW MONTH "; 

char *months[] = { "Month 0", "January", "February", "March", 
"April", "May", "June", "July", "August", 

"September", "October", "November", "December" 

} ; 


char spaces]] = " "; 

char infotext[] = " Number Amount Payee \ 

Memo Date"; 

char *string, *srch_payee, *srch memo; 

char rule[] = "-\ 

_II . 


long balance, start amnt, end amnt; 

OBJECT *menu addr, *check addr, *newacct_addr, *newfile addr, 
*newdate_addr, *srchdial_addr, *cancdial_addr, 
*recndial addr, 

*rprtdial_addr, *lkmndial addr, *srtodial_addr; 

FILE *acctfile, *mfile; 
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char *get_tedinfo_str (); 
FILE *opn nw_auto (); 
long str_to_long (); 

struct check { 

char number[5]; 
char payee[31]; 
char memo[31] ; 
char date[9] ; 
long amount; 
char cancel[2]; 

In¬ 


struct check checks[500]; 
struct check srch_checks[1000]; 
struct check *cur chk_strc; 

TEDINFO *ob tedinfo; 


main () 

{ 

appl_init (); /* 

open^vwork (); /* 

do_mcheck(); /* 

v^clsvwk (handle); /* 

Setcolor ( 2, oldcolr ); /* 
appl_exit (); /* 

} 


Initialize application. */ 
Set up workstation. */ 
Go do MicroCheck. */ 
Close virtual workstation. */ 
Reset color register. */ 
Back to the desktop. */ 


do_mcheck() 

{ 

oldcolr = Setcolor ( 2, -1 ); 

Setcolor ( 2, 0x005 ); 

if ( (res = Getrez ()) != HIGH && res != MEDIUM ) 

form alert (1,"[0] [MicroCheck ST runs|only in high or \ 
medium |resolution.][OK]") ; 
else { 

graf mouse ( ARROW, &dum ) ; 
strcpy ( acct_name, "NONE" ); 
strcpy ( cur_chk_num, "0000" ); 
balance = 0; 
month = -1; 

edit top = cur_top = num^trans = num_chks = num_^deps = 0; 
left = saved = TRUE; 

search = canceling = full draw = FALSE; 
cur chk_strc = checks; 
get_date () ; 


if ( Irsrc^load 
form^alert ( 
else { 

rsrc_gaddr ( 
rsrc^gaddr ( 
rsrc_gaddr ( 
rsrc_gaddr ( 
rsrc_gaddr ( 
rsrc_gaddr ( 
rsrc^gaddr ( 
rsrc_gaddr ( 


( "\MICROCHK.RSC" ) ) 

1, "[1][MICROCHK.RSC missing!][Okay]" 


R 

TREE, 

MENUBAR, 

R 

TREE, 

CHEKDIAL 

R 

TREE, 

NEWADIAL 

R 

TREE, 

FILEDIAL 

R 

TREE, 

DATEDIAL 

R 

TREE, 

SRCHDIAL 

R 

TREE, 

CANCDIAL 

R 

TREE, 

RECNDIAL 


&menu_addr ); 
&check_addr ); 
&newacct_addr ); 
Snewfile addr ); 
&newdate_addr ); 
&srchdial_addr ); 
&cancdial_addr ); 
&recndial addr ); 
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} 


rsrc_gaddr ( R_TREE, RPRTDIAL, 
rsrc_gaddr ( R_TREE, LKMNDIAL, 
rsrc_gaddr ( R TREE, SRTODIAL, 
menu bar ( menu addr, TRUE ); 
set_menu_entries (); 
wind_get(0, WF_WORKXYWH, &fullx, 
w hi = wind_create ( 0, fullx, 
w h2 = wind_create ( PARTS, fullx, fully, fullw, fullh ); 
wind—set ( w h2, WF NAME, noacct, 0, 0 ); 
wind_set ( w h2, WF INFO, infotext, 0, 
wind open ( w hi, fullx, fully, fullw, 
wind—open(w_h2,fullx,fully,fullw, 316 - 
calc__vslid ( 1 ) ; 
calc_hslid ( NUM^COLUMNS ); 
full = FALSE; 
loaded = FALSE; 


&rprtdial_addr ); 
&lkmndial addr ); 
Ssrtodial addr ); 


Sfully, &fullw, sfullh ); 
fully, fullw, fullh ); 


0 ) ; 

fullh ); 

162*(res==MED)); 


get_event (); 

menu bar ( menu addr, FALSE ); 
wind_close ( w h2 ); 
wind^delete ( w^h2 ); 
wind_close ( w hi ); 
wind delete ( w^hl ); 
rsrc free () ; 


get_event () 

{ 

int h, event; 
all_done = FALSE; 
while ( !all_done ) { 

event = evnt_multi(MU_KEYBD|MU_MESAG|MU_BUTTON,NUMJ3LICKS, 

LEFT_BUTTON, BUTTON-DOWN, 

0,0,0,0,0,0,0,0,0,0,msg_buf,0,0, 
Smousex,Smouse^y,&dum,&dum,&key, 

Snum_clicks); 

if ( event & MU_KEYBD ) 
handle—keys (); 

if ( event & MU_MESAG ) 
handle—messages (); 

if ( event & MU_BUTTON ) 
handle_button (); 

} 

} 


set—menU—entries () 

{ 

menU—ienable ( menu addr, 
menu ienable ( menu addr, 
menU—ienable ( menu addr, 
menu ienable ( menu addr. 


CLOSEMBR, loaded ); 
OPENMBR, !loaded ); 
NEWACCNT, !loaded ); 
QUIT, TRUE ); 
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menu 

ienable 

( menu 

addr, 

ENTER, loaded ); 

menu 

ienable 

( menu 

addr, 

SEARCH, 

loaded ); 

menu 

ienable 

( menu 

addr. 

CHKCAN, 

loaded ); 

menu 

ienable 

( menu 

addr. 

NEWMNTH, 

loaded ); 

menu 

ienable 

( menu 

addr. 

RECONCIL 

, loaded ); 

menu 

ienable 

( menu 

addr. 

PRNTWIND 

, loaded ); 

menu 

ienable 

( menu 

addr. 

PRNTREG, 

loaded ); 

menu 

ienable 

( menu 

addr. 

NEWYEAR, 

!loaded ); 

menu 

ienable 

( menu 

addr. 

CHKAUTO, 

loaded ); 

menu 

ienable 

( menu 

addr. 

NEWDATE, 

TRUE ); 

menu 

ienable 

( menu 

addr. 

IMPORT, 

!loaded ); 


} 


calc vslid ( line cnt ) 
int line cnt; 

{ 

int lines avail, vslid_siz, pos; 
if ( line_cnt == 0 ) line cnt = 1; 

wind get ( w_h2, WF WORKXYWH, Swrkx, Swrky, Swrkw, &wrkh ); 
lines_avail = wrkh / charh; 

vslid_siz = 1000 * lines_avail / line_cnt; 
wind_set ( w h2, WF^VSLSIZE, vslid siz, 0, 0, 0 ); 
pos = (int) ( (float) (cur_top) ) / 

( (float) (line_cnt - lines_avail) ) * 1000; 
wind_set ( w^h2, WF VSLIDE, pos, 0, 0, 0 ); 


calc_hslid ( col_cnt ) 
int col_cnt; 

{ 

int cols__avail, hslid_siz, pos, lft; 

if ( left ) 
lft = 0; 

else 

lft = 16; 

wind get ( w h2, WF WORKXYWH, Swrkx, Swrky, Swrkw, Swrkh ); 
cols_avail = wrkw / charw; 

hslid_siz = (int) ((1000L * (long) cols_avail)/ (long) col_cnt); 
wind_set ( w h2, WF HSLSIZE, hslid siz, 0, 0, 0 ); 
pos = (int) ( (float) (lft) ) / 

( (float) (col_cnt - cols_avail) ) * 1000; 
wind_set ( w^h2, WF HSLIDE, pos, 0, 0, 0 ); 


open vwork () 

{ 

int i; 


handle = graf handle ( Scharw, Scharh, Sdum, Sdum); 
for ( i=0; i<10; work in[i++] = 1 ); 
work in[10] = 2; 

v opnvwk ( work in, Shandle, work out ) ; 
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get_date () 

{ 

int date, day, ninth, year; 
char d[3], m[3], y[4]; 

date = Tgetdate (); 
day = date & OxOOlf; 
mnth = (date >> 5) & OxOOOf; 
year = ((date >> 9) & 0x007f) + 80; 

year = year % 100; 
sprintf ( d, "%d", day ); 
sprintf ( m, "%d", mnth ); 
sprintf ( y, "%d", year ); 
if ( mnth < 10 ) { 

date_but[0] = 'O'; 
cur_date[0] = 'O'; 
strcpy ( &date_but[1], m ); 
strcpy ( Scurdate[1], m ); 

} 

else { 

strcpy ( date_but, m ); 
strcpy ( cur_date, m ); 

} 

date_but[2] = '/'; 
if ( day < 10 ) { 

date_but[3] = 'O'; 
cur_date[2] = 'O'; 
strcpy ( &date_but[4], d ); 
strcpy ( &cur_date[3], d ); 

} 

else { 

strcpy ( &date_but[3], d ); 
strcpy ( Scurdate[2], d ); 

} 

date_but[5] = '/'; 
if ( year < 10 ) { 

date_but[6] = 'O'; 
cur_date[4] = 'O'; 

strcpy ( &date_but[7], y ); 
strcpy ( &cur_date[5], y ); 

} 

else { 

strcpy ( &date_but[6], y ); 
strcpy ( &cur_date[4], y ); 

} 

} 


handle_keys () 

{ } 

handle_messages () 

{ } 

handle_button () 

{ } 
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Program Listing #3 


ST-Basic 


100 OPEN"R" ,#1, "A:MICROCHK.RSC" ,16:FIELD#1,16 AS B$ 


110 A$="" :FOR 1=1 TO 16:READ 
120 A=VAL ("&H"+V$) :PRINT 
130 LSET B$=A$:R=R+1:PUT 1,R 
140 CLOSE 1:PRINT:PRINT "ALL 
1000 data 00,00,0C,42,09,32, 
1010 data 06,64,19,C2,00,90, 
1020 data 00,00,19,EE,20,20, 
1030 data 55,4E,54,20,20,20, 
1040 data 20,20,20,20,20,20, 
1050 data 20,20,20,00,20,4E, 
1060 data 5F,5F,5F,5F,5F,5F, 
1070 data 5F,5F,5F,5F,00,58, 
1080 data 58,58,58,58,58,58, 
1090 data 20,20,20,20,20,20, 
1100 data 20,20,20,20,20,20, 
1110 data 3A,20,5F,5F,5F,5F, 
1120 data 5F,5F,5F,5F,5F,5F, 
1130 data 58,58,58,58,58,58, 
1140 data 58,58,58,58,58,00, 
1150 data 20,20,20,20,20,00, 
1160 data 5F, 5F,5F,5F,5F,5F, 
1170 data 58,58,58,58,58,58, 
1180 data 20,53,74,61,74,65, 
1190 data 20,20,20,20,20,20, 
1200 data 5F,5F,5F,2D,5F,5F, 
1210 data 39,39,00,20,20,20, 
1220 data 6E, 63, 65,3A, 20,24, 
1230 data 39,39,39,39,39,39, 
1240 data 00,20,44,65,73,6B, 
1250 data 43,68,65,63,6B,73, 
1260 data 55,74,69,6C,69,74, 
1270 data 74,20,4D,69,63,72, 
1280 data 2D,2D,2D,2D,2D,2D, 
1290 data 2D,2D,2D,2D,2D,2D, 
1300 data 63,63,65,73,73,6F, 
1310 data 65,73,6B,20,41,63, 
1320 data 20,00,20,20,44,65, 
1330 data 72,79,20,33,20,20, 
1340 data 63,65,73,73,6F,72, 
1350 data 73,6B,20,41,63,63, 
1360 data 00,20,20,44,65,73, 
1370 data 79,20,36,20,20,00, 
1380 data 20,4F,20,4F,70,65, 
1390 data 6F,73,65,2E,2E,2E, 
1400 data 2D, 2D,2D,2D,2D,2D, 
1410 data 20,4D,20,4E,65, 77, 
1420 data 20,45,20,45,6E,74, 
1430 data 65,61,72,63,68,2E, 
1440 data 6E,63,69,6C,65,2E, 
1450 data 65,6C,2E,2E,2E,00, 
1460 data 00,20,57,20,57,69, 
1470 data 52,65,67,69,73,74, 
1480 data 20,59,65,61,72,2E, 
1490 data 2E,2E,2E,00,20,49, 
1500 data 00,4F,4B,00,43,41, 
1510 data 20,00,20,4E,61,6D, 


V$:IF V$="*" THEN 140 
;:A$=A$+CHR$(A):NEXT 
:GOTO 110 
DONE!" 


09, 
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.74, 
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. 74 
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5F, 

5F, 
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. 5F, 

5F, 

. 5F, 

00, 

58, 

. 58, 

. 58 
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58, 

58, 

. 58, 

58, 

. 58, 

00, 

20, 

. 20, 

. 00 

3A, 

20, 

5F, 

. 5F, 

00, 

,41, 

41, 

00, 

. 20, 

. 20 

20, 

00, 

20, 

. 5A, 

69, 

. 70, 

3A, 

20, 

. 5F, 

. 5F 

5F, 

5F, 

00, 

. 39, 

39, 

. 39, 

39, 

39, 

. 39, 

. 39 

20, 

20, 

20, 

, 20, 

00, 

. 20, 

42, 

61, 

. 6C, 
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5F, 

5F, 

. 5F, 
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. 2E, 
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. 39 
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4F, 
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. 45, 
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00, 
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.46, 

69, 

. 6C, 

65, 
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. 00, 
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00, 
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. 50, 

72, 

. 69, 

6E, 

74, 

. 00, 

. 20 

69, 

65, 

73, 

, 00, 

20, 

. 20, 

41, 

62, 

. 6F, 

. 75 

6F, 

43, 

68, 

. 65, 

63, 

. 6B, 

2E, 

2E, 

. 2E, 

. 00 

2D, 

2D, 

2D, 

, 2D, 

2D, 

, 2D, 

2D, 

2D, 

. 2D, 

, 2D 

2D, 

00, 

20, 

, 20, 

44, 

. 65, 

73, 

6B, 

. 20, 

,41 

72, 

79, 

20, 

. 31, 

20, 

. 20, 

00, 

20, 

. 20, 

, 44 

63, 

65, 

73, 

, 73, 

6F, 

.72, 

79, 

20, 

. 32, 

. 20 

73, 

6B, 

20, 

.41, 

63, 

. 63, 

65, 

73, 

. 73, 

. 6F 

00, 

20, 

20, 

44, 

65, 

. 73, 

6B, 

20, 

,41, 

. 63 

79, 

20, 

34, 

. 20, 

20, 

. 00, 

20, 

20, 

,44, 

. 65 

65, 

73, 

73, 

. 6F, 

72, 

■79, 

20, 

35, 
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. 20 

6B, 

20, 

41, 

. 63, 

63, 

. 65, 

73, 

73, 

. 6F, 

. 72 

20, 

4E, 

20, 

. 4E, 

65, 

.77, 

2E, 

2E, 

, 2E, 

. 00 

6E, 

2E, 

2E, 

. 2E, 

00, 

. 20, 

43, 

20, 

. 43, 

. 6C 

00, 

2D, 

2D, 

, 2D, 

2D, 

, 2D, 

2D, 

2D, 

, 2D, 

, 2D 

2D, 

00, 

20, 

. 51, 

20, 

. 51, 

75, 

69, 

,74, 

. 00 

20, 

4D, 

6F, 

. 6E, 

74, 

. 68, 

2E, 

2E, 

, 2E, 

. 00 

65, 

72, 

2E, 

. 2E, 

2E, 

. 00, 

20, 

53, 

. 20, 

. 53 

2E, 

2E, 

00, 

. 20, 

52, 

. 20, 

52, 

65, 

. 63, 

, 6F 

2E, 

2E, 

00, 

. 20, 

50, 

. 20, 

43, 

61, 

. 6E, 

. 63 

20, 

41, 

20, 

.41, 

75, 

.74, 

6F, 

2E, 

, 2E, 

. 2E 

6E, 

64, 

6F, 

.77, 

20, 

. 20, 

00, 

20, 

,47, 

.20 

65, 

72, 

20, 

. 00, 

20, 

. 59, 

20, 

4E, 

. 65, 

. 77 

2E, 

2E, 

00, 

. 20, 

44, 

. 20, 

44, 

61, 

,74, 

. 65 

20, 

49, 

6D, 

. 70, 

6F, 

,72, 

74, 

2E, 

, 2E, 

, 2E 

4E, 

43, 

45, 

. 4C, 

00, 

. 40, 

20, 

20, 

. 20, 

. 20 

65, 

3A, 

20, 

. 5F, 

5F, 

. 5F, 

5F, 

5F, 

, 5F, 

. 20 
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1520 

data 

O 

O 

58,58,58, 

58,58 

1530 

data 

45, 

20,00,00, 

00,4E 

1540 

data 

5F, 

5F,5F,5F, 

00,5F 

1550 

data 

39, 

39,39,39, 

00,4F 

1560 

data 

45, 

41,52,43, 

48,20 

1570 

data 

00, 

4D,4F,4E, 

54,48 

1580 

data 

43, 

41,4E,43, 

45,4C 

1590 

data 

53, 

00,20,20, 

00,20 

1600 

data 

39, 

00,20,20, 

00,20 

1610 

data 

20, 

20,20,20, 

00,20 

1620 

data 

00, 

39,39,39, 

39,00 

1630 

data 

5F, 
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Program Listing #4 


ST-Check BUG Data 


100 data 21,544,391,421,536,604,620,730,588,553,5008 
1050 data 812,51,861,789,558,647,7,957,827,635,6144 
1150 data 737,975,751,724,699,870,633,890,758,697,7734 
1250 data 756,811,842,883,780,724,794,753,699,733,7775 
1350 data 784,774,742,793,873,769,843,752,791,818,7939 
1450 data 821,726,785,760,837,692,854,762,741,934,7912 
1550 data 751,740,782,815,738,708,801,666,730,860,7591 
1650 data 706,845,677,575,670,35,30,844,805,574,5761 
1750 data 595,20,73,869,851,768,870,848,812,821,6527 


1850 data 815,823,897,840, 
1950 data 773,714,845,854, 
2050 data 828,881,866,999, 
2150 data 691,895,799,888, 
2250 data 862,784,857,759, 
2350 data 772,851,893,815, 
2450 data 812,742,522,605, 
2550 data 706,553,721,590, 
2650 data 656,802,776,690, 
2750 data 592,730,695,785, 
2850 data 790,661,822,740, 
2950 data 801,693,870,541, 
3050 data 854,924,615,868, 
3150 data 841,504,834,875, 
3250 data 579,869,921,570, 
3350 data 850,877,527,599, 
3450 data 875,539,856,582, 
3550 data 572,865,576,607, 
3650 data 866,862,530,677, 
3750 data 711,521,873,874, 
3850 data 592,865,892,582, 
3950 data 883,917,612,895, 
4050 data 725,503,846,859, 
4150 data 535,853,909,560, 
4250 data 868,926,555,853, 
4350 data 873,542,862,892, 
4450 data 598,856,857,583, 
4550 data 890,893,579,893, 
4650 data 882,571,864,890, 
4750 data 603,879,921,575, 
4850 data 867,943,581,872, 
4950 data 750,536,880,909, 
5050 data 539,850,879,540, 
5150 data 203,203 


778,916,876,847,871,934,8597 
901,953,48,895,50,916,6949 


56,956,51,875,829,761,7102 
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CHAPTER 28 - A COMPLETE GEM APPLICATION - PART 2 


IN CHAPTER 27 WE LOOKED at the portion of the MicroCheck ST source code that declared all of the 
global variables used in the program and initialized both GEM and the program itself. Essentially, you 
could say that the first part of the source code did all the start-up housekeeping. With all the 
housekeeping (or most of it) out of the way, we are ready to explore the program itself. 

Recall that a GEM application is controlled by "events." Whenever the user attempts any form of 
input, whether it be accessing the menu bar, typing a key, clicking the mouse or fiddling with one of a 
window's controls, GEM sends our application a message that describes what the user wants to do. 
It's up to us, as the programmers, to decide how to handle and interpret these messages. We can 
even ignore them if we want to. 

The source code we looked at in Chapter 27 included a function called get_event(), which used a call 
to evnt_multi() to retrieve events from GEM and route them to the appropriate parts of the program. 
In MicroCheck ST we are interested in only three types of events: keyboard events, mouse-button 
events, or GEM messages. These three events are handled in MicroCheck ST by the functions 
handle_keys(), handle_button(), and handle_messages(), respectively. 

Last time, we represented these functions in our source code as "stubs," do-nothing functions that 
simply fulfill the linker's need for a label. This allowed us to compile and link a small portion of the 
program. Without the stubs, the linker would have complained about the missing functions and not 
allowed us to get a running program. Now we'll be replacing the handle_messages() stub with the 
real function, adding to MicroCheck ST the ability to handle GEM message events. At this point you 
should load the portion of MicroCheck 

ST we looked at in Chapter 27 and delete the handle_messages() stub. You should then add the code 
shown in Listing 1. Once Listing 1 has been merged, you will be able to compile and link it. When you 
run the resulting program, rather than ending up with a mostly empty screen as we did in the 
previous program segment, the addition of the handle_messages() function and some of its 
subordinate functions, allows the window to be filled in and the buttons at the bottom of the screen 
to be drawn. We'll see why soon. 

Unfortunately, we still haven't added a quit function to the program, so once who have run the 
program, the only way to get back to the Desktop is to turn off your computer. Now, let's examine 
the new functions. 

Function handle_messages() 

As we've discussed before, when GEM sends a message, it stores it in an array that we must provide. 
In MicroCheck ST this array is msg_buf(). The array element msg_buf[0] will contain the type of 
message we've received. 

Now, look at the top of Listing 1, where you'll find the function handle_messages(). This function 
simply takes the message type that was stored in msg_buf[0] and uses it in a switch statement to 
route the message to the appropriate part of the program. The switch is followed by seven case 
statements that handle menu messages, redraw messages, window-fulled messages, arrow 
messages, vertical-slider messages, horizontal-slider messages, and window-closed messages, 
respectively. 

For now, we will deal only with redraw messages and window-fulled messages. The functions 
do_redraw() and do_full() handle those. The other functions needed for handle_messages() - 
do_menu(), do_arrow(), do_vslide(), do_hslide(), and do_wind_close() - are represented in this 
chapter's code segment by stubs. 
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Notice that, in the call to do_redraw(), we are passing the address of msg_bug[4] cast into a pointer 
to GRECT (a structure which is defined in the header file OBDEFS.H and which contains the 
coordinates for a GEM rectangle). The array elements msg_buf[4] through msg_buf[7] contain the 
coordinates for the work area of the window that needs to be redrawn. 

Function do_redraw() 

This function steps through the rectangle list, redrawing all portions of the windows that need to be 
refreshed. This includes the "invisible" window I mentioned in Chapter 27 . The information buttons 
on the bottom of the screen are drawn as a result of a redraw message for this window. 

The function do_redraw(), after locking the windows (to prevent corruption by such occurrences as a 
menu bar dropping down), steps through the rectangle list for each window, calculating the 
rectangles that need to be redrawn. The redraw itself is handled by the function draw_interior(), 
which we'll get to in a moment. After the rectangle list is empty, we unlock the window and control 
returns back to get_event(), where we wait for another event. 

Function draw_interior() 

This function handles the actual redraw operations. The structure clip, passed to this function from 
do_redraw(), contains the coordinates of the rectangle to be redrawn. First we turn off the mouse 
and set the drawing mode to "replace." Then, if the redraw message is for window #1, the invisible 
window, we calculate the coordinates, based on the current resolution, of the portion of the window 
to be redrawn, and redraw both that rectangle and the boxes on the bottom of the screen. (The only 
rectangle that'll ever be redrawn in the invisible window is the section of the screen below the visible 
window, the part of the screen that contains the buttons. If the visible window, the one that displays 
the check data, is fully opened, we'll never get a redraw message for the invisible window since it is 
completely covered.) 

If the redraw message isn't for window #1, it has to be for window #2, the visible window. First we 
check the status of the flag full_draw. If its value is FALSE, we are not going to be updating the entire 
window, so we set a clipping rectangle to the portion of the window's work area we are going to 
redraw. A call to draw_rec() redraws the window rectangle. 

The check data for MicroCheck ST is stored in an array of structures called checks[]. The first check is 
in element 0 of the array, the second in element 1, and so on. The position within the array at which 
a check is located is its index. 

We find out how many lines of check data will fit in the window (lines_avail) based on the flag full, 
which indicates whether the window has been fully opened. Next we find out how many lines we 
need to display (lines_shown), by subtracting from the total number of checks (cur_count) the index 
of the check data shown at the top of the window (cur_top). (This doesn't have to be the first record 
in the checks[] array; if the user has used the vertical scroll bar or down arrow, the index for the 
check data at the top of the window could be almost anything, up to the maximum minus the 
number of checks that'll fit in the window.) 

If lines_avail is larger than lines_shown, we have more space in the window then we have checks to 
fill it (when starting with cur_top), so we calculate a new cur_top in an attempt to show as many 
checks as possible, without any blank space at the bottom. If cur_top ends up less than 0, we don't 
have enough check data in the array to fill the window. In this case, we just set cur_top to the first 
check in the array. 

We then set the vertical and horizontal sliders, call updte_chk_wind() to print the check data that 
should appear in the window, turn off the full_draw flag, turn off clipping (otherwise, we won't be 
able to print anything to the screen unless its coordinates are within the clipping rectangle), and turn 
the mouse back on. 
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Function draw_rec() 

This function does nothing more than draw a filled rectangle at the coordinates passed in the 
structure rec. The interior style, fill style, and color of the rectangle are also passed to the function, 
although in most cases when we're redrawing a window, we'll want a solid white rectangle. Passing 
the extra information makes the function a little more flexible. Notice also that, as usual, whenever 
we draw anything on the screen, we shut off the mouse. This is important if we want to keep our 
screen clean. 

Function set_clip() 

Here we set the clipping rectangle, the portion of the screen in which we want to restrict our 
drawing, to the coordinates passed in the structure rec. The integer flag is a Boolean variable that 
tells the function whether we're turning the clipping on or off. (TRUE turns it on.) 

Function updte_chk_wind() 

This function simply prints the necessary check data to the newly updated window (with a call to 
prnt_chk_wnd()). We get the coordinates of the window's work area and use those values to 
calculate, based on the character size and the check data index, the position within the window in 
which to print the data. We need to use the character size because high-resolution characters are a 
different height (16 pixels) from medium-resolution characters (eight pixels). Remember that the 
integer cur_top holds the index for the check data that should be displayed at the top of the window. 

Function prnt_chk_wnd() 

It's here that we actually print the check data to the screen. The index into the check array and the 
row at which the data should be printed are passed to this function from updte_chk_wind(). This 
function uses basic C text handling, so you should be able to understand it easily. Of special note, 
however, is the structure cur_chk_strc and the use of the flag left. 

Because MicroCheck ST uses two different structures for holding check data — one for the regular 
monthly file and one for data obtained with the search function — we use the pointer cur_chk_strc to 
point to the currently active structure. This simplifies handling the two structures, making it so we 
don't need to know whether the program is in the edit or search mode. 

The flag left indicates the position of the window's horizontal slider. If the slider is all the way to the 
left (left is TRUE), we display all the check data except the date, which is in the right-hand, unseen 
portion of the window. If the slider is to the right, we display the date, but not the check's cancel 
indicator or number, which are now in the left-hand, unseen portion of the window. 

Function format_date() 

Because the date for a check is stored in the format mmddyy, it must be converted to the more 
typical mm/dd/yy format before it is printed in the check window. The function format_date() takes 
care of this chore for us. The pointer dl is the address of a character array where the final formatted 
date will be stored, and the pointer d2 is the address of the date in its unformatted form. 

Function draw_buttons() 

Across the bottom of the MicroCheck ST screen, there is a series of six boxes that contain various 
information about the currently opened account. The function draw_buttons(), along with a lot of 
help from its subordinate functions, prints the information in the boxes. 
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Function set_buttons() 

Most of the data to be displayed in the boxes is in integer or long-integer format, so we must first, 
using sprintf(), convert it to strings. Note that the strings to be displayed in the boxes are stored in 
character arrays whose names end with _but. 

The raw data to be converted is stored in four global variables: The long integer balance is the 
account's balance; and the integers num_trans, num_chks, and num_deps are the total number of 
transactions, the number of checks, and the number of deposits in the currently opened month, 
respectively. 

Function buttonQ 

This function does the actual drawing of the boxes. The pointer strl is the address of the box's label, 
the pointer str2 is the address of the information to print, and xl is the X coordinate of the box being 
updated. The function first calculates the position in which the boxes should be drawn. It then, with a 
little help from center_butstring(), draws the boxes. 

Function center_butstringQ 

This function centers and prints the text in the boxes. A pointer to the text to be printed, along with 
the X and Y coordinates for the box, is passed to the function from buttonQ. 

Function do_full() 

The check-display window in MicroCheck ST can be opened to only two sizes. The smallest size holds 
16 checks and allows the user the view the information boxes on the bottom of the screen. The full- 
size window can hold up to 20 checks, but covers the information boxes. 

We keep track of the window's current size with the flag full. Whenever we get a window-fulled 
message from GEM (this happens when the user clicks on the full box in the upper-right corner of the 
window), we check full and set the window's size accordingly. We are actually concerned only with 
the window's height, and because a high-resolution screen is twice the vertical resolution of a 
medium-resolution screen, we use the integer variable res, which holds the current screen 
resolution, to calculate the window's height. 

Time For Another Break 

In Chapter 29, we will examine still more of MicroCheck ST. (I bet you can hardly wait.) 


Port: HYPertext by Lonny Pursell & PDF by DrCoolZic (jig) - VI.0 Oct. 2010 


Page 282/321 



C-MANSHIP COMPLETE - by CLAYTON WALNUT 


Program Listing #1 

handle_messages () 

{ 

switch ( msg_buf[0] ) { 

case MN_SELECTED: 
do^menu (); 
break; 

case WM REDRAW: 

do_redraw ( (GRECT *) &msg_buf[4] ); 
break; 

case WM_FULLED: 
do_full (); 
break; 

case WM ARROWED: 
do^arrow (); 
break; 

case WM^VSLID: 
do_vslide (); 
break; 

case WM_HSLID: 

do_hslide (); 
break; 

case WM^CLOSED: 

do_wind_close (); 
break; 

} 

} 


do_redraw ( reel ) 

GRECT *recl; 

{ 

GRECT rec2 ; 

wind update ( BEG_UPDATE ) ; 
wind_get ( msg_buf[3], WF_FIRSTXYWH, 

&rec2.g_x, &rec2.g_y, &rec2.g_w, &rec2.g_h 

while ( rec2.g w && rec2.g h ) { 

if ( rc_intersect ( reel, &rec2 ) ) 

draw interior ( rec2 ); 
wind get ( msg buf[3], WF NEXTXYWH, 

&rec2.g_x, &rec2.g_y, &rec2.g_w, &rec2.g 

} 

wind_update ( END_UPDATE ); 


do_full () 

{ 

if ( !full ) 

wind set ( w h2, WF_CURRXYWH, fullx, fully, fullw, 
else 

wind_set ( w_h2, WF CURRXYWH, 


) ; 


h ) ; 


fullh ); 
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fullx, fully, fullw, 316 -162*(res==MED) ); 
calc_vslid ( cur_count ); 
full = !full; 


do_menu () 

{ } 

do^arrow () 

{ } 


do_vslide () 

{ } 

do_hslide () 

{ } 

do_wind_close () 

{ } 


draw interior ( clip ) 

GRECT clip; 

{ 

GRECT r; 

int lines avail, lines shown; 


graf mouse ( 

M OFF, 

0L ) ; 

vswr mode ( 

handle. 

MD REPLACE 

if ( msg buf 

[3] == 

w hi ) { 

if ( res 

== HIGH 

) { 

r. g x 

= 1; 


r.g_y 

= 337; 


r. g w 

= 638; 


r. g h 

= 63; 


} 

else { 

r. g x 

= 1; 


r.g y = 167 

r 


r. g w 

= 638; 


r. g h 

= 32; 


} 

draw rec 

( r, 2, 

4, GREEN ); 

draw buttons (); 



else { 

if ( !full draw ) 

set_clip ( TRUE, clip ) ; 
wind get(w h2,WF WORKXYWH, &r.g x, 
draw_rec ( r, 2, 8, WHITE ); 
if ( full ) 


&r 


lines avail = 20; 
else 

lines_avail = 15; 

lines shown = cur^count - cur_top; 
if ( lines avail > lines_shown ) { 

cur top = cur^count - lines avail; 
if ( cur_top < 0 ) 
cur_top = 0; 


g_y. 


&r.g w. 


&r,g_h); 
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} 

if ( cur_count == 0 ) 
calcvslid ( 1 ); 
else 

calc^vslid ( cur^count ); 
calc_hslid ( NUM_COLUMNS ); 
updte_chk_wind (); 
full_draw = FALSE; 
set_clip ( FALSE, clip ); 

} 

graf_mouse ( M_ON, OL ); 


draw rec ( rec, inter, fill, color ) 
GRECT rec; 

int inter, fill, color; 

{ 

int pxy[4]; 


graf mouse ( M OFF, OL ); 
vsf_interior ( handle, inter ); 
vsf_style ( handle, fill ); 
vsf_color ( handle, color ); 
pxy[0] = rec.gx; 
pxy[l] = rec.gy; 
pxy[2] = rec.g x + rec.gw - 1; 
pxy[3] = rec.g_y + rec.g^h - 1; 
vr^recfl ( handle, pxy ) ; 
graf_mouse ( M_ON, OL ) ; 


set_clip ( flag, rec ) 
int flag; 

GRECT rec; 

{ 

int pxy[4]; 

pxy[0] = rec.gx; 

pxy[l] = rec.g_y; 

pxy[2] = rec.g x + rec.g w - 1; 

pxy[3] = rec.g_y + rec.g_h - 1; 

vs_clip ( handle, flag, pxy ); 

} 


updte chk wind () 

{ 

int i, y; 

wind get ( w_h2, WF WORKXYWH, Swrkx, &wrky, Swrkw, &wrkh ); 
i = cur_top; 
y = 0; 

while ( (i < cur_count) && (i < cur_top + wrkh / charh) ) { 
prnt_chk wnd ( i, wrky + charh + y * charh ); 

++i ; 

++y; 

} 

} 
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prnt chk_wnd ( index, row ) 
int index, row; 

{ 

char a[40], s[10] ; 
if ( left ) { 

v_gtext ( handle, 6, row, cur^chk strc[index].cancel ); 
v_gtext ( handle, 25, row, cur chk_strc[index].number ); 
sprintf ( a, "$%51d.%021d", 

cur chk strc[index].amount/100, 
cur^chk strc[index].amount%100 ); 
v_gtext ( handle, 77, row, a ); 

v_gtext ( handle, 169, row, cur_chk_strc[index].payee ); 
strcpy ( a, cur_chk_strc[index].memo ); 
a [24] = 0; 

v_gtext ( handle, 424, row, a ); 

} 

else { 

v_gtext ( handle, 9, row, cur^chk^strc[index].payee ); 

v_gtext ( handle, 264, row, cur chk strc[index].memo ); 

strcpy ( s, cur_chk_strc[index].date ); 

format_date ( a, s ); 

v_gtext ( handle, 520, row, a ); 

} 

} 


draw_buttons() 

{ 


set_buttons (); 

button ( "BALANCE", bal_but, 35 ); 
button ( "# TRANS", trans_but, 131 ) 
button ( "# CHECKS", check but, 227 
button ( "# DEP", dep_but, 323 ); 
button ( "MONTH", mnthjout, 419 ); 
button ( "DATE", date_but, 515 ); 


set_buttons () 

{ 

if ( balance < 0 && balance > (-100) ) 

sprintf ( bal^but, "$-%ld.%021d" , balance/100, 
labs(balance%100) ); 

else 

sprintf ( bal_but, "$%ld.%021d" , balance/100, 
labs(balance%100) ); 

sprintf ( trans but, "%d", num trans ); 
sprintf ( check but, "%d", num_chks ); 
sprintf ( dep_but, "%d", num_deps ); 
if ( month == -1 ) 

strcpy ( mnth but, "NONE" ); 
else 

strcpy ( mnth but, months[month] ); 


button ( strl, str2, xl ) 
char *strl, *str2; 
int xl; 

{ 
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int x2, yl, y2; 
int pxy[10]; 


} 


x2 = xl + 88; 
yl = 174 * res; 
y2 = 198 * res; 

vswr_mode ( handle, MD REPLACE ); 
vsf_color ( handle, WHITE ) ; 
pxy[0] = xl; 
pxy[1] = yl; 

pxy[2] = x2 ; 

pxy[3] = y2 ; 

v bar ( handle, pxy ) ; 

pxy[3] = yl; 

pxy[4] = x2; 

pxy[5] = y2; 

pxy[6] = xl; 

pxy[7] = y2; 

pxy[8] = xl; 

pxy[9] = yl; 


vsl width ( handle, 3 ); 
vsl_color ( handle, BLACK ); 
v_pline ( handle, 5, pxy ); 
center_butstring ( strl, xl, 184); 
center_butstring ( str2, xl, 194); 


center_butstring ( str, xl, y ) 
char *str; 
int xl, y; 

{ 

int x, x2; 


x2 = xl + 88; 

x = ((x2-xl)-(strlen(str)*8))/2+xl; 
v gtext ( handle, xl+5, y * res, " 
v_gtext ( handle, x, y * res, str ) ; 


format_date ( dl, d2 ) 
char *dl, *d2; 

{ 


strcpy ( 

dl. 

d2 : 

) ; 

dl [2] = 




strcpy ( 

&dl 

[3] , 

&d2 [2 

dl[5] = 




strcpy ( 

&dl 

[6] , 

&d2 [4 
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CHAPTER 29 - A COMPLETE GEM APPLICATION - PART 3 

In this chapter we'll continue examining the MicroCheck ST source code by adding the functions we 
need to get the menu bar working. We'll also be looking at the code that controls the sliders and 
arrows in our window. 

Marching Onward 

Listing 1, found at the end of this chapter, is the third portion of the MicroCheck ST source code. 

Load the source code you've typed so far (from Chapters 27 and 28), delete the do_menu(), 
do_wind_close(), do_arrow(), do_vslide(), do_hslide(), and handle_button() stubs (those do-nothing 
functions that we added for the linker's sake), and add Listing 1. Leave in the handle_keys() stub. 

When you run the program (after compiling it, of course), you'll notice two big changes: the Quit 
option of the File menu now works (hallelujua!) and the horizontal scroll bar on the window works. 

In fact, the entire menu bar is now working, but since we haven't added the code necessary to 
perform the functions chosen from the menu (except Quit), most of the menu choices still do 
nothing. Likewise, all the window controls are now in working order, but since the window is 
displaying nothing, most of them seem to be non-functional. 

Now let's examine the new functions. 

Function do_menu() 

Here we take the MU_MESAG (a menu message) passed from GEM and interpret it, sending program 
execution to the appropriate function. As you may recall, the object number of the menu title can be 
found in the third element of the message buffer, and the object number of the selected entry within 
the menu can be found in the fourth element of the message buffer (in our case, msg_buf[3] and 
msg_buf[4j). 

To interpret the message, we use nested switch statements. The outer switch checks msg_buf[3] to 
find out which of the menus was accessed. The inner switch statements (one for each of the menus) 
uses msg_buf[4] to route the user's request to the right function. 

If you look closely at do_menu(), you'll see that every menu and every selection within each menu is 
represented here. Although the function is long, it is really quite simple. The only other thing of note 
here is the call, at the end of the function, to menu_normal(), which deselects (turns off the 
highlighting) the menu title chosen. 

Function do_wind_close() 

This function is called whenever the user clicks on the window's close box or selects the Close entry 
of the File menu. Because MicroCheck ST has three modes -- edit, search and cancel -- 
do_wind_close() has three sections, each of which handles one of the modes. 

Since we'll be modifying the window, the first thing we must do is call wind_update() to lock the 
window from any other redraws. (At the end of the function, we unlock the window with the same 
function.) 

If the user is in the search or cancel mode, we need to return to the edit mode. The first two sections 
of the if statement handle these situations. In both cases, the current mode is turned off (returning 
the program to edit mode), the window name is changed to show that the user is back in the edit 
mode, the window is redrawn, and the menu entries are set appropriately. (Some of them are not 
available in every mode, so, according to the mode, some are enabled and some are disabled). 
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If we're already in the edit mode when the user selects Close, we need to close the account. First, we 
bring up an alert box, asking the user if he's sure he wants to close the account. 

If he is, we save the account to disk, blank the window, reset the menu entries (almost everything 
will be disabled) and reset the window's title bar to show the user that no account is open. 

Function handleJbuttonO 

Whenever the mouse button is clicked on MicroCheck ST's work area, this function is called. If the 
mouse pointer was over the check window, then the user either wants to edit a check or wants to 
mark it as cancelled. 

If the program is not in the search or cancel modes, we call edit() to bring up the check dialog for the 
check he has selected, otherwise we call canc_chk(), the function that places the program in the 
cancel mode and allows the user to cancel transactions. 

Function do_arrowQ 

Whenever the user clicks the mouse pointer on one of the window's arrows or slider tracks (not on 
the slider itself), GEM sends us a WM_ARROWED message. This message comes in eight different 
flavors (only six of which are of interest to MicroCheck ST). The actual type of arrow message is 
contained in the fourth element of the message buffer. So in the case of MicroCheck ST, we call 
do_arrow(), passing it the value of msg_buf[4]. 

The user may be asking to move up or down a line, up or down a page, right or left a line (or 
character, actually), or right or left a page. Since MicroCheck ST allows the user to scroll the window 
right or left only by a full page, we don't need to worry about the WA_LFLINE and WA_RTLINE 
messages. 

As with do_menu(), we use a switch statement to route the user's request to the appropriate 
function. 

Function do_uppage() 

If the user clicked in the portion of the slider track above the slider, do_uppage() takes over. Here we 
simply find out how many lines will fit in the window, subtract that value from the index number for 
the check displayed at the top of the window to calculate a new cur_top, and redraw the window. 

Function do_dnpage() 

If the user clicked in the portion of the slider track below the slider, he wants to move down a page. 
We call do_dnpage(), which works much like do_uppage() except that we add lines_available (the 
number of lines that'll fit in the window) to cur_top rather than subtract it. 

Function do_uplineQ 

When the window's up arrow is clicked, do_upline() springs into action, moving the window up one 
line. Moving up or down a single line is, if it's to be done elegantly, much more complex than moving 
an entire page. When we move up or down a full page, we have no choice but to redraw the entire 
window in the normal way, since none of the data we want to display is available anywhere on the 
screen. 

However, when we move up or down a single line, all the data we need, except one line, is on the 
screen. If we want the scrolling action to be smooth, we can't just redraw the entire window in the 
conventional way. Instead, we raster (block move) the portion of the window containing data we can 
use up or down one line, then add the new data at the top or bottom, depending on which way we're 
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moving. These block moves of screen memory are fast and help create the illusion of the window 
scrolling a line at a time. 

So, in do_upline() we subtract 1 from cur_top (the index of the check shown at the top of the 
window), raster a portion of the window, starting with the top line and extending down to the next 
to the last line, down one position, then replace the top line with the new current top. Simple (well, 
almost) and elegant. 

Function do_dnline() 

This function works almost exactly like do_upline(), except it moves the window down one line 
instead of up. 

Function do_vslide() 

If the user chooses to use the vertical slider, do_vslide() will accommodate him. Handling the sliders 
is much more complicated than handling the arrows or slider tracks because the user can place the 
slider anywhere within the track. We need to calculate what portion of the data to display based on 
the slider's new position. 

The fourth element of the message buffer contains the new position of the slider. We use this value 
first to see if the slider has actually moved to a new position. If the slider has been moved, we 
calculate its position within our "document" (in MicroCheck ST's case, the list of checks), set cur_top 
to the appropriate check index (the one that'll now appear at the top of the window) and redraw the 
window, placing the slider in its new location. 

Function do_hslideQ 

The horizontal slider works in much the same fashion as its vertical counterpart. The main difference 
is that, in MicroCheck ST, we allow this slider to have only two positions: full right or full left. This 
makes the job much easier, since we don't have to do a lot of fancy calculations. Instead, we use the 
flag left to keep track of the horizontal slider's current position. When the user moves the slider, all 
we have to do is toggle our flag and change the position of the slider, redrawing the window as we 
do. 

The only complication is that, since we are going to be displaying a different portion of the data, we 
need to change the labels in the window information line. This is easy to do with a quick call to 
wind_set(). 

Function do_quitQ 

When the user is ready to leave the program and return to the desktop, he'll select the Quit selection 
of the File menu (at least, he will if we wants a safe exit). When he does, do_quit() will ask if he's sure 
he wants to quit. If he is, his data will be saved and the flag all_done will be set to true. This flag will 
then break us out of the get_event() loop and return the program to the end of do_mcheck() where 
all our windows and GEM resources will be deleted from memory. 

Putting It In Order 

Now that, over the last few chapters, we've put together a large chunk of source code, you might 
want to rearrange some of the functions so that the higher level functions are at the top of the 
program and the lower level functions are at the bottom. This "top down" organization will make the 
program easier to read and trace. 
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Program Listing #1 

do^menu () 

{ 

int button; 

switch ( msg_buf[3] ) { 

case DESK; 

form^alert(1, "[0] [ MicroCheck ST by Clayton Walnum \ 
| | Copyright 1989 by Clayton Walnum ][CONTINUE]"); 

break; 

case FILEBAR: 

switch ( msg_buf[4] ) { 

case NEWACCNT: 

do_newacct (); 
break; 

case OPENMBR; 

button = get_acct (); 
if ( button ) 

open^acct ( filename ); 
break; 

case CLOSEMBR: 

do_wind_close (); 
break; 

case NEWMNTH: 

do new mnth (); 
break; 

case QUIT: 

do_quit (); 
break; 

} 

break; 

case CHECKS: 

switch ( msg_buf[4] ) { 

case ENTER: 

do_enter (); 
break; 

case SEARCH: 

do_search (); 
break; 

case CHKCAN: 

do_check_canc (); 
break; 

case RECONCIL: 

do_reconcil (); 
break; 

case CHKAUTO: 
do_auto (); 
break; 
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} 

break; 
case PRINT: 

switch ( msg_buf[4] ) { 

case PRNTWIND: 

print wind (); 
break; 

case PRNTREG: 
print_reg (); 
break; 


case UTILITY: 

switch ( msg_buf[4] ) { 

case NEWYEAR: 

do_new__year () ; 
break; 

case NEWDATE: 

get_new_date (); 
break; 

case IMPORT: 

do_import (); 
break; 


} 

break; 

} 

menu tnormal ( menu addr, msg_buf[3], TRUE ); 


do_wind_close () 

{ 

int button; 

GRECT r; 

wind get ( w_h2, WF WORKXYWH, &r.g x, &r.g y, &r.g w, &r.g_h); 
wind update ( BEG_UPDATE ); 
if ( search ) { 

search = FALSE; 

cur_top = edit_top; 

cur count = num^trans; 

cur chk strc = checks; 

srch trans = 0; 

set_menu_entries (); 

strcpy ( windname, acct name ); 

strcpy ( Swindname[strlen(windname)], ": Edit mode" ); 
wind set ( w h2, WF NAME, windname, 0, 0 ) ; 
draw interior ( r ); 

} 

else if ( canceling ) { 

if ( !saved ) 

save month ( monthfile ); 
canceling = FALSE; 
strcpy ( windname, acct^name ); 

strcpy ( Swindname[strlen(windname)], ": Edit mode" ); 
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wind set ( w_h2, WF NAME, windname, 0, 0 ) ; 
draw interior ( r ); 
set_menu_entries (); 

} 

else if ( loaded ) { 

button = form_alert ( 1, "[2][Do you want to close|this \ 
account?][YES|NO]") ; 

if ( button == YES ) { 

do_save (); 

draw rec ( r, 2, 8, WHITE ); 
set_menu_entries (); 

wind set ( w h2, WF NAME, noacct, 0, 0 ); 

} 

} 

wind_update ( END_UPDATE ); 


handle_button () 

{ 

wind get ( w h2, WF WORKXYWH, Swrkx, &wrky, Swrkw, &wrkh ); 
if ( mouse y > wrky && mousej < wrky + cur count * charh + 4 
&& mouse y < wrky + wrkh && mouse x > wrkx 
&& mouse x < wrkx+wrkw && num_clicks == 1 ) 
if ( !search && !canceling ) 

edit (); 

else if ( canceling ) 
canc_chk (); 

} 


do^arrow () 

{ 

switch ( msg_buf[4] ) { 

case WA_UPPAGE: 
do_uppage (); 
break; 

case WA DNPAGE: 
do_dnpage (); 
break; 

case WA_UPLINE: 
do_upline (); 
break; 

case WAJDNLINE: 
do_dnline (); 
break; 

case WA LFPAGE: 

case WA RTPAGE: 
do_hslide (); 
break; 


} 


} 


do vslide () 
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{ 

GRECT r; 

int lines avail; 

wind get ( w h2, WF VSLIDE, &r.g x, &r.g_y, &r.g w, &r.g h ); 
if ( r.g x != msg buf[4] ) { 

wind^update ( BEG^UPDATE ); 

wind get ( w h2, WF WORKXYWH,&r.g x,&r.g y,&r.g w,&r.g h) ; 
lines^avail = r.g_h / charh; 
cur_top = ( long) msg_buf[4]* 

( (long) cur_count- (long) linesavail)/1000L; 
wind_set ( w h2, WF_VSLIDE, msg buf[4], 0, 0, 0 ); 
draw interior ( r ); 
wind_update ( END_UPDATE ) ; 

} 

} 


do_hslide () 

{ 

GRECT r; 


wind get ( w h2, WF HSLIDE, &r.g x, &r.g_y, &r.g w, &r.g h ); 
if ( r.g x != msg_buf[4] ) { 

wind update ( BEG UPDATE ); 

wind get ( w h2, WF WORKXYWH, &r.g x,&r.g y,&r.g w,&r.g h); 
left = (left; 
if ( left ) { 

wind set ( w h2, WF INFO, infotext, 0, 0 ); 
wind^set ( w~h2, WF_HSLIDE, 0, 0, 0, 0 ); 

} 

else { 

wind set ( w h2, WF INFO, Sinfotext[20], 0, 0 ); 
wind_set ( w_h2, WF_HSLIDE, 166, 0, 0, 0 ); 

} 

draw interior ( r ); 
wind_update ( END_UPDATE ); 

} 


do_uppage () 

{ 

GRECT r; 

int lines avail; 
wind update ( BEG_UPDATE ); 

wind^get ( w_h2, WF WORKXYWH,&r.g x, &r.g_y,&r.g w,&r.g h ); 
lines avail = r.g h / charh; 
cur_top -= lines_avail; 
if ( cur_top < 0 ) 
cur_top = 0; 

wind_update ( END_UPDATE ) ; 
draw interior ( r ); 

} 


do_dnpage () 

{ 

GRECT r; 

int lines avail; 
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wind update ( BEG_UPDATE ); 

wind get ( w h2, WF WORKXYWH,&r.g x,&r.g_y,&r.g w,&r.g h) ; 
lines avail = r.g h / charh; 
cur top += lines_avail; 

if ( cur top > cur count - lines avail ) 
cur^top = cur_count - lines_avail; 
draw interior ( r ); 
wind_update ( END_UPDATE ); 


do_upline () 

{ 

MFDB s, d; 
GRECT r; 
int pxy[8]; 


if ( cur_top != 0 ) { 

wind update ( BEG UPDATE ); 
cur_top -= 1; 

wind get ( w h2, WF WORKXYWH,&r.g x,&r.g y,&r.g w,&r.g h 
set_clip ( TRUE, r ) ; 
graf^mouse ( M_OFF, OL ); 
s.fd addr = OL; 
d.fd addr = OL; 
pxy[0] 
pxy[1] 
pxy[2] 
pxy[3] 
pxy[4] 
pxy[5] 
pxy[6] 
pxy[7] 
vro_cp 

prnt_chk wnd ( cur_top, r.g 
set_clip ( FALSE, r ); 
calc_vslid ( cur_count ); 
wind_update ( END_UPDATE ); 
graf mouse ( M ON, OL ); 


r.g_x; 



r.g_y + 

2; 


r . g x + 

r.g w ; 


r .g_y + 

r . g h - 

charh 

r.g_x; 



1 

+ 

charh + 

2; 

r . g x + 

r.g w ; 


r.g_y + 

r . g h - 

2; 

( handle, S ONLY, pxy 


2 ; 


&s, &d 
charh ); 


do_dnline () 

{ 

MFDB s, d; 

GRECT r; 
int pxy[8]; 

int lines_avail, index; 

wind get ( w h2, WF WORKXYWH, &r.g x, &r.g y, &r.g w, &r.g h 

) ; 

lines_avail = r.g h / charh; 

if ( (cur_top + lines_avail) < cur_count ) { 

wind update ( BEG UPDATE ); 
cur_top += 1; 

index = cur top + lines avail - 1; 
set_clip ( TRUE, r ) ; 
graf mouse ( M_OFF, OL ); 
s.fd_addr = OL; 
d.fd addr = OL; 
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} 


1*(res= 


pxy[0] = r.g_x; 
pxy[l] = r.g_y + charh + 2 
pxy[2] = r.g x + r.g w; 
pxy[3] = r.g_y + r.g_h - 1; 
pxy[4] = r.g_x; 

pxy[5] = r.g_y + 3 -1*(res==MED); 
pxy[6] = r.g x + r.g w; 
pxy[7] = r.g_y + r.g h - charh - 1; 
vro_cpyfm ( handle, S_ONLY, pxy, &s, 
prnt chk wnd ( index, r.g_y + lines 
set_clip ( FALSE, r ) ; 
calc_vslid ( cur_count ); 
wind_update ( END_UPDATE ); 
graf mouse ( M_ON, OL ); 


do_quit () 

{ 

int button; 

button = formalert(1, "[2][Are you sure 
quit?][YES|NO] "); 

if ( button == YES ) { 

search = FALSE; 
all done = TRUE; 
if ( [saved ) 
do_save (); 

} 

} 

save month () 

{ } 

do_new_year() 

{ } 

do^new mnth() 

{ } 

do_newacct () 

{ } 

get^acct() 

{} 

open_acct() 

{ } 

get_new_date() 

{} 

do_save() 

{ } 

do_import () 

{ } 

do_reconcil() 

{ } 


=MED); 


&d ) ; 

avail * charh ); 


you|want to 
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canc_chk() 

{ } 

do_check_canc() 

{ } 

print reg() 

{ } 

do_search () 

{ } 

print wind() 

{ } 

do_auto() 

{ } 

do_enter() 

{ } 

edit() 

{ } 
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CHAPTER 30 - A COMPLETE GEM APPLICATION - PART 4 


Believe it or not, there are many people who prefer to do things the old-fashioned way, people who 
despise such newfangled contraptions as menu bars and other mouse-driven devices that make 
them lift their chubby fingers from the keyboard. You and I, of course, are great fans of GEM, but 
whenever we design a program, we have to remember that not everyone shares our good taste. Put 
simply, programs should have keyboard alternatives whenever possible, especially for selecting 
functions from a menu bar. 

Needless to say, MicroCheck ST provides keyboard selection for every function in the menu bar. The 
user who considers the ST's mouse a furless rodent unworthy of his touch may type a Control-key 
combination to select any function he desires. In this chapter, we'll be looking at the portion of 
MicroCheck ST's source code that handles the Control-key selections. We'll also look at the routines 
that allow the user to begin a new account. 

Compiling 

Listing 1 is this chapter's portion of the MicroCheck ST source code. Add it to the combined source 
code from the previous installments, then delete the handle_keys() and do_newacct() stubs from the 
resulting file. 

After compiling the program, you'll find that you can now select functions from the menu bar by 
pressing a Control-key combination. For example, pressing Control-Q will exit the program. 

Pressing Control-N, on the other hand, will activate the "New" selection of the File menu. A dialog 
box will appear, asking for your name, address, and account balance, after which a second dialog box 
will ask for the filename you wish to use for the account. This filename can be up to six characters 
long. When you've typed in the filename, MicroCheck ST will save the information you typed in the 
new-account dialog box to a file with an .MCK extension and will create all the monthly data files for 
your new account. 

Now let's take a closer look at how all this works. 

Function handle_keys() 

If you look at the selections in the menu bar, you'll see that each has a single letter next to it. This is 
the key to press along with Control in order to select that function from the keyboard. But just having 
the letters on the menu isn't enough, of course. We have to retrieve the key presses from the 
keyboard (which we do by watching for MU_KEYBD events with evnt_multi()), and when we get a 
Control-key combination, we have to route it to the appropriate portion of the program. 

This is handled by the function handle_keys(), which does much the same work as do_menu(), except 
that we're using Control-key values in the switch statements rather than a menu message. Another 
major difference is that we're using the loaded, search, and canceling flags to determine which menu 
functions are active. We didn't have to do this in do_menu() because inactive menu selections are 
grayed-out and are not selectable by the user. Notice that in handle_keys(), we are highlighting the 
appropriate menu title with menu_tnormal(), just as we did in do_menu(). This tells the user which 
menu he is working with. 

All of the values for the Control-key combinations in handle_keys() are defined at the top of the 
program. 
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Function do_newacct() 

Whenever the "New" selection of the File menu is selected or a Control-N is typed, the function 
do_newacct() is called. This function brings up the dialog box for entering the information needed to 
start a new MicroCheck ST account. 

First, we call clear_newacct() to make sure any information that was previously entered into the 
dialog is erased. Next, we call up the dialog box in the usual way and activate it with a call to 
form_do(). 

The variable choice will contain the number of the object used to exit the dialog. If this object was 
the OK button (NEWOK), we call the function check_newacct() to make sure all the information in 
the dialog was filled in. If the dialog has empty fields (okay is FALSE), we redraw the dialog (the dialog 
is still on the screen, but the buttons haven't been redrawn to their deselected state) and loop back 
to form_do() in order to let the user try again. 

If the user clicked the OK button and the dialog was properly filled in, we call newacct_file(), which 
will get a filename from the user for the new account and call the functions that will write the new- 
account information out to the disk. 

If the user clicked the cancel button (NEWCANCL), we clear the dialog and close it, then go back to 
wait for another event. 

Function check_newacct() 

This function simply checks to see that none of the fields in the dialog have been left empty. We use 
the flag okay to communicate this information back to the calling function. 

First, we set okay to TRUE. Then we use a for loop to cycle through the editable text objects in the 
dialog, checking that none are empty. (An empty field will begin with a Note that, should you 
ever use this method in any of your own programs, the objects you're checking must have been 
created sequentially, all at the same time. Otherwise, you can't use a for loop to check the objects.) If 
an empty field is found, okay is set to FALSE and an alert box warns the user that he must complete 
the form. 

Function newacct_file() 

Most of this function is dedicated to getting a filename from the user and combining it with the right 
path specification. 

First, we get the address of the string in the filename dialog box and clear it with a null. (With dialog 
boxes, you can clear a string with the or by the usual null character.) Next, we zero out the string 
filename and call up the dialog box. If the user exits the dialog with the OK button (FILEOK), we call 
check_file() to be certain a filename has been entered. If it hasn't, we loop back to let the user try 
again. 

If the user entered the filename properly, we retrieve it from the dialog, copy it into acct_name[] (a 
string that will be used in the window's title bar), then add the complete pathname and the .MCK 
extension. We then open the file in binary-write mode, and a call to write_new_info() writes all the 
account information to the file, as well as creates the monthly data files. 

A call to open_acct() actually opens the account so the user can enter checks if he wishes. (Note that 
open_acct() is represented only by a stub at this point; so when you run this portion of the program, 
although you can create a new account, the account cannot actually be opened.) 

If the user exited the dialog by clicking on the CANCEL button (FILECANC), we exit the dialog without 
starting a new account. 
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Function clear_newacct() 

This function simply steps through each of the editable text fields in the new-account dialog box, 
clearing them of whatever information they may already contain. 

Function get_tedinfo_strQ 

In order to handle dialog boxes with editable text fields, it's necessary you know how to handle 
TEDINFO structures. This function simplifies the process of getting the address of a string in an 
editable text field. Simply pass it the address of the tree and the number of the object, and it'll return 
the address of the string. 

Function check_fileQ 

In order to open a file for a new account, we must, of course, have a legal filename. The validation 
string for the dialog's editable text field will make sure the user enters only legal filename characters, 
but it's up to us to be certain that the field is filled in. This function simply checks the object 
FILENAME to be sure it's not empty. If it is empty, we scold the user with an alert box. 

Function no_decimal() 

In MicroCheck ST, we have to deal with numbers in two ways. The user, since he is entering amounts 
as dollars and cents, needs to use decimal numbers; that is, he needs to enter his values with dollars 
on the left of a decimal point and cents on the right. Unfortunately, this means using floating point 
numbers, which are infamously inaccurate due to the rounding operations performed when 
calculating with these numbers. 

In order to avoid rounding errors, MicroCheck ST calculates not with both dollars and cents, but only 
with cents. For MicroCheck ST, $100 isn't 100.00, but rather 10,000. So every time the user enters a 
value, we need, as the first step to making the conversion from dollars to cents, to combine both the 
dollar and cent portions of the number. 

The function no_decimal() accomplishes that task using conventional string-handling techniques. The 
string to be converted will have one of three formats: dollars and no cents, dollars and cents, or 
cents and no dollars. The strings as retrieved from the dialog will take one of the forms shown in the 
first column of the chart below (none of the strings contains trailing spaces): 


String 

Actual value 

After no_decimal() 

99 

$99.00 

9900 

99 99 

99.99 

9999 

9999999 

99999.99 

9999999 

9 

.90 

90 

99 

.99 

99 


The strings, when they are retrieved from a dialog box, contain no decimal points; instead, dollars 
and cents are separated by spaces. If the entire field is full, there are no spaces at all. Without spaces 
delimitating the two numbers, you have to know the field length in order to separate the dollars and 
cents; in this case, dollars can be up to five digits and cents, of course, can be up to two. 

The chart on the previous page shows the string obtained from the dialog, the value it represents, 
and the value no_decimal() will return, respectively. Note that the value returned is the number of 
cents, but it's still in string, not numeric, form. 

Function str_to_long() 

Once we have the number of cents in string form, we need to convert it to long-integer form. The 
function str_to_long() handles this by multiplying each digit in the string times its corresponding 


Port: FlYPertext by Lonny Pursell & PDF by DrCoolZic (jig) - VI.0 Oct. 2010 


Page 300/321 


C-MANSHIP COMPLETE - by CLAYTON WALNUT 


value in the pwrs[] array. Each product is added to num until the end of the string is reached. The 
long integer num will contain the final result. 

Function write_new_info() 

In order to begin a new account, MicroCheck ST must write out the information retrieved from the 
new-account dialog to the .MCK file, as well as create each of the 13 monthly data files. These files 
will be named fileO.DAT through filel2.DAT, where "file" is the filename that was entered into the 
filename dialog box. 

This task is accomplished by write_new_info(). First, we write out the user's name and address to the 
file we opened back in newacct_file() (acctfile). Then we retrieve the account balance, convert it to 
long integer and write it out to the same file. 

The last step is to create the 13 monthly data files. (Yes, I know there are only 12 months. The extra 
file, the one numbered "0," is storage for uncanceled checks from the previous year, necessary 
whenever the "new year" function is used.) 

We use a for loop to repeat the file-creation process 13 times. The loop variable, x, is used as the file 
number and is tacked onto the end of the filename the user typed into the filename dialog box. The 
complete pathname is tacked onto the filename, as is the extension ".DAT." When the filename is 
complete, we open the file (in binary mode) and write out a zero, after which the file is closed. (The 
first word [two bytes] of the monthly files is the number of transactions in the file; since a new file 
has no transactions, we start off with a zero.) 

Conclusion 

That's it for another chapter. If anything I've described in this or the last few chapters doesn't make 
sense to you, you should review the topic in question. If you want to write full-GEM applications, you 
need to know all this stuff! 
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Program Listing #1 

handle_keys () 

{ 

int button; 


if ( loaded && ! search 
switch ( key ) { 

case CNTL_A: 

menu tnormal 
do_auto (); 
menu tnormal 
break; 

case CNTL^E: 

menu tnormal 
do_enter (); 
menu tnormal 
break; 

case CNTL_M: 

menu tnormal 
do_new_mnth () 
menu tnormal ( 
break; 


&& !canceling ) 

menu addr, CHECKS, 
menu addr, CHECKS, 

menu addr, CHECKS, 
menu addr, CHECKS, 

menu addr, FILEBAR, 
menu addr, FILEBAR, 


case CNTL_P: 

menu tnormal ( menu addr, CHECKS, 
do_check_canc (); 

menu tnormal ( menu addr, CHECKS, 
break; 

case CNTL_R: 

menu tnormal ( menu addr, CHECKS, 
do_reconcil (); 

menu^tnormal ( menu addr, CHECKS, 
break; 


if ( ! loaded ) 

switch ( key ) { 

case CNTL_N: 

menu tnormal ( menu addr, FILEBAR, 
do_newacct (); 

menu tnormal ( menu addr, FILEBAR, 
break; 

case CNTL_0: 

menu tnormal ( menu addr, FILEBAR, 
button = get_acct (); 
if ( button ) 

open_acct ( filename ); 
menu tnormal ( menu addr, FILEBAR, 
break; 


case CNTL_Y: 

menu tnormal ( menu addr, UTILITY, 
do_new_year (); 

menu tnormal ( menu addr, UTILITY, 
break; 


FALSE ); 
TRUE ); 

FALSE ); 
TRUE ); 

FALSE ); 
TRUE ); 

FALSE ); 
TRUE ); 

FALSE ); 
TRUE ); 


FALSE ); 
TRUE ); 

FALSE ); 

TRUE ); 

FALSE ); 
TRUE ); 
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case CNTL I: 


menu tnormal 

( menu addr, UTILITY, FALSE ) 

do import () 

r 

menu tnormal 

( menu addr, UTILITY, TRUE ); 

break; 

} 


switch ( key ) { 


case CNTLJ2: 


menu tnormal ( 

menu addr, FILEBAR, FALSE ); 

do quit (); 


menu tnormal ( 
break; 

menu addr, FILEBAR, TRUE ); 

case CNTLJS: 



if ( loaded && !canceling ) { 

menu tnormal ( menu addr, CHECKS, FALSE ); 
do_search (); 

menu tnormal ( menu addr, CHECKS, TRUE ); 

} 

break; 

case CNTL_C: 

if ( loaded ) { 

menu tnormal ( menu addr, FILEBAR, FALSE ); 
do_wind_close (); 

menu tnormal ( menu addr, FILEBAR, TRUE ); 

} 

break; 

case CNTL_D: 

menu tnormal ( menu addr, UTILITY, FALSE ); 
get_new_date (); 

menu tnormal ( menu addr, UTILITY, TRUE ); 
break; 

case CNTL_W: 

if ( loaded ) { 

menu^tnormal ( menu addr, PRINT, FALSE ); 
print wind (); 

menu tnormal ( menu addr, PRINT, TRUE ); 

} 

break; 

case CNTL_G: 

if ( loaded ) { 

menu tnormal ( menu addr, PRINT, FALSE ); 
print_reg (); 

menu^tnormal ( menu addr, PRINT, TRUE ); 

} 

break; 

} 

} 


do_newacct () 

{ 

int choice, okay; 

int dial_x, dial y, dial w, dial_h; 
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clear_newacct (); 

form^center(newacct addr,&dial_x, &dial_y, &dial_w, &dial_h); 
form dial(FMD^START,0,0,10,10,dial_x,dial y,dial_w,dial h) ; 
obj c_draw(newacct_addr,0,8,dialx,dial_y,dial_w,dial_h); 

do { 

choice = form do ( newacct addr, NEWNAME ); 
newacct addr[choice].ob_state = SHADOWED; 

switch ( choice ) { 

case NEWOK; 

okay = check_newacct (); 
if ( lokay ) 

objc_draw ( newacct_addr, 0, 8, 

dial x, dial y, dial_w, dial_h ); 

else 

newacct_file (); 
break; 

case NEWCANCL: 

clear_newacct (); 

} 

} 

while ( okay == FALSE && choice != NEWCANCL ); 

form dial(FMD^FINISH,0,0,10,10,dial_x,dial y,dial_w,dial_h); 


check_newacct () 

{ 

int x, okay; 
okay = TRUE; 

for ( x=NEWNAME; x<=NEWBALNC; ++x ) { 

string = get_tedinfo_str ( newacct_addr, x ); 
if ( string[0] == '@' ) 
okay = FALSE; 

} 

if ( lokay ) 

form alert(1, " [ 1 ] [You must complete|the form to start | \ 
a new account!][OK]") ; 
return ( okay ); 

} 


newacct_file () 

{ 

int choice, okay, x; 

int dial_x, dial y, dial w, dial_h; 

string = get tedinfo str ( newfile addr, FILENAME ); 
string[0] = 0; 

for ( x=0; x<64; filename[x++]=0 ); 
newfile addr[NEWOK].ob^state = SHADOWED; 

form^center(newfile addr,&dial_x,&dial y,&dial_w,&dial_h); 
form dial(FMD_START,0,0,10,10,dial x,dial__y,dial w,dial h); 
objc^draw(newfile_addr,0,8,dial_x,dial y,dial_w,dial h); 


Port: HYPertext by Lonny Pursell & PDF by DrCoolZic (jig) - VI.0 Oct. 2010 


Page 304/321 


C-MANSHIP COMPLETE - by CLAYTON WALNUT 


do { 

choice = form^do ( newfile^addr, FILENAME ); 
newfile addr[choice].ob_state = SHADOWED; 

switch ( choice ) { 

case FILEOK: 

okay = check_file (); 
if ( !okay ) 

objc_draw ( newfile_addr, 0, 8, 

dial x, dial y, dial_w, dial_h ); 

else { 

string = get tedinfo str(newfile addr,FILENAME); 
strcpy ( acct^name, string ); 
filename[0] = Dgetdrv () + 'a'; 
filename[1] = 

Dgetpath ( &filename[2], DFLT DRV ); 
filename[strlen(filename)] = '\\ ; 
strcpy ( Sfilename[strlen(filename)], string ); 
strcpy ( Sfilename[strlen(filename)], ".MCK" ); 
acctfile = fopen ( filename, "bw" ); 
if ( acctfile != 0 ) { 

write new info (); 
open_acct ( filename ); 

} 

} 

break; 

case FILECANC: 

string = get_tedinfo_str ( newfile_addr, FILENAME ); 
string[0] = 0; 

} 

} 

while ( lokay && choice != FILECANC ); 

form dial(FMD FINISH,0,0,10,10,dial x,dial y,dial w,dial_h); 


clear_newacct () 

{ 

int x; 

for ( x=NEWNAME; x<=NEWBALNC; ++x ) { 

string = get tedinfo_str ( newacct addr, x ); 
string[0] = '@' ; 

} 

newacct_addr[NEWCANCL].ob state = SHADOWED; 


char *get_tedinfo_str ( tree, object ) 

OBJECT *tree; 
int object; 

{ 

TEDINFO *ob_tedinfo; 

ob_tedinfo = (TEDINFO *) tree[object].ob_spec; 
return ( ob_tedinfo->te_ptext ); 
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check_file () 

{ 

int okay; 
okay = TRUE; 

string = get tedinfo str ( newfile addr, FILENAME ); 
if ( strlen ( string ) == 0 ) { 

form alert(1 ,"[ 1][Invalid filename!][OK]" ); 
okay = FALSE; 

} 

return ( okay ); 


no_decimal ( s ) 
char *s; 

{ 

int x, i, d, len; 
char s2 [20], s3 [20]; 

strcpy ( s2, s ); 
len = strlen ( s2 ); 
i = 0; 
d = FALSE; 

for ( x=0; x<len; ++x ) 

if ( d && s2[x] != ' ' ) 

++i ; 

else 

if ( s2[x] == ' ' ) 

d = TRUE; 

if ( i == 0 && len < 6 ) 

strcpy ( &s2[len], "00" ); 
else 

if ( i == 1 || len == 6 ) 

strcpy ( &s2[len], "0" ); 


i = 0; 

for ( x=0; x<strlen (s2); ++x ) 

if ( s2[x] ! = ' ' & s2[x] !='.') 

s3[i++] = s2[x]; 
s3[i] = 0; 
strcpy ( s, s3 ); 

} 

long str_to_long ( s ) 
char *s; 

{ 

int x, len, factor; 
long num; 

num = 0; 

len = strlen ( s ); 

factor = len - 1; 

for ( x=0; x<len; ++x ) 

num += (long) ( s[x] - 'O' ) * pwrs[factor--]; 

return ( num ); 


write new info () 

{ 

int len, x; 


Port: HYPertext by Lonny Pursell & PDF by DrCoolZic (jig) - VI.0 Oct. 2010 


Page 306/321 


C-MANSHIP COMPLETE - by CLAYTON WALNUT 


char s[10], tmpfile[64]; 
FILE *f; 


string = get^tedinfo str ( newacct addr, NEWNAME ); 
fwrite ( string, 1, 26, acctfile ); 

string = get tedinfo str ( newacct addr, NEWADDR ); 
fwrite ( string, 1, 26, acctfile ); 

string = get tedinfo str ( newacct addr, NEWCITY ); 
fwrite ( string, 1, 26, acctfile ); 

string = get tedinfo str ( newacct addr, NEWSTATE ); 
fwrite ( string, 1, 3, acctfile ); 

string = get^tedinfo str ( newacct addr, NEWZIP ); 
fwrite ( string, 1, 10, acctfile ); 

string = get_tedinfo str ( newacct addr, NEWBALNC ); 

no decimal ( string ); 

balance = str_to_long ( string ); 

fwrite ( Sbalance, 1, 4, acctfile ); 

if ( fclose ( acctfile ) != 0 ) 

form alert ( 1, "[l][File close error!][OKAY] ") ; 
for ( x=0; x<13; ++x ) { 

sprintf ( s, "%d", x ); 
strcpy ( &s[strlen(s)], ".dat" ); 

ob tedinfo = (TEDINFO *) newfile addr[FILENAME].ob_spec; 
tmpfile[0] = Dgetdrv () + 'a'; 
strcpy ( &tmpfile[l], ); 

Dgetpath ( &tmpfile[strlen(tmpfile)], DFLT DRV ); 
strcpy ( &tmpfile[strlen(tmpfile)], "\\" ); 

strcpy ( &tmpfile[strlen(tmpfile)], ob_tedinfo->te_ptext ); 

strcpy ( Stmpfile[strlen(tmpfile)] , s ); 

if ( ( f = fopen ( tmpfile, "bw" ) ) == NULL ) 

form alert ( 1, "[1][Error creating file!][OK]" ); 


else 

fwrite ( Szero, 
if ( fclose ( f ) 
form alert ( 


2, 1, f ); 

= 0 ) 

1, "[1][File close error!][OK] 
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CHAPTER 31 - A COMPLETE GEM APPLICATION - PART 5 


In chapter 30 we added the code needed to create a new MicroCheck ST account. Unfortunately, 
once the account was created, we still weren't able to open it. Now we'll add the program segment 
that'll not only handle that task, but also will enable us to modify the date shown in the date 
information box at the bottom of the MicroCheck ST screen. 

Listing 1 is the new source code. Merge it with the combined source code from the previous four 
chapters and delete the open_acct(), do_new_mnth(), save_month(), and get_new_date() stubs from 
the previous portion. 

Now compile the program and run it. Start a new account. After that procedure is complete, a dialog 
box will appear, asking for the month you want to work on. Select the month. The account will be 
opened, and the information boxes on the screen will be updated for that account. 

Now choose the New Date option of the Utilities drop-down menu. Another dialog will appear. Type 
in a new date. When you select the dialog's OK button, the date you have typed will appear in the 
date information box at the bottom of the screen. Let's look at the new functions. 

Function open_acctQ 

This function is called whenever the user wants to open an account or has just finished creating a 
new one. It gets as input a pointer to the filename of the account the user wants to open. At the 
beginning of the function, it attempts to open the .MCK file for the account. If it fails, an alert box 
warns the user and no further processing is done. 

If the fopen() call is successful, we read in the information that's stored in the file. The file format is 
shown below. All of the information is in character format, except the account balance, which is a 
long integer: 


Bytes 

Data Stored 

1-26 

Name 

27-52 

Street Address 

53-68 

City 

69-78 

Not Currently Used 

79-81 

State 

92-95 

Account Balance (long int) 


As the data is read in, it's formatted the way it will appear in the check-entry dialog box. After 
reading all the data, we close the file and plug the pointers to the name and address strings into the 
ob_spec for each of the appropriate fields in the check-entry dialog box: 

check addr[CHKNAME].ob spec=chkname; 
check addr[CHKSTREET].ob_spec=chkstreet; 
check addr[CHKCITY].ob spec=chkcity; 

In the above, check_addr is the address of the check-entry dialog box; CHKNAME, CHKSTREET and 
CHKCITY are the names of string objects inside the dialog box; and ob_spec is the pointer to the 
string to be displayed for that object. 

After setting the dialog-box strings, we call do_new_mnth(), which gets the month selection from the 
user and calls the functions necessary to actually open the files. If the account gets opened okay, the 
flag loaded will be TRUE, and we'll call set_menu_entries() in order to enable and disable the 
appropriate entries in the drop-down menu. 
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Function do_new_mnth() 

Here we first set the title string of the month-selection dialog box to "NEW MONTH" by placing a 
pointer to the string (newm) into the object's ob_spec field: 

cancdial addr[CANCSTRG].ob spec=newm; 

Here, cancdial_addr is the address of the month-selection dialog box and CANCSTRG is a string object 
within the dialog box. 

The integer value choice, the button on which the user clicked to exit the month-selection dialog box, 
is returned from a call to get_month(), the function that handles the dialog itself. If the user exited 
with the OK button, we save the current month's data if it needs to be (saved equals FALSE) and call 
open_new_month() to open the files. 

Function save_month() 

In this function we first take the filename of the file to save (the pointer to which is passed into the 
function as file) and change the extension to "BAK." We then delete any backup file that may already 
exist for that month and rename the old data file as the new backup file. We then open a new file 
with the filename pointed to by file (warning the user with an alert box if we get an error), after 
which we write that month's data out to the file. 

The first two bytes written are the number of transactions in the file (in integer form). Then, using a 
for loop, we call save_check() for each check record in the check structure, writing the data to disk, 
after which we close the file. 

Now all we have to do is save the new account balance. Our call to fseek() moves the file pointer in 
91 bytes from the beginning of the file, which is where the balance is stored. We save the balance 
and close the file. 

Function open_new_month() 

The first task here is to discover which month the user selected from the month-selection dialog box. 
We do that by using a for loop to scan through each of the button objects in the dialog, to see which 
one is selected. (Note that this technique will work only if the button objects were created in 
numerical order when the dialog was first designed.) Based on which button was selected, we set the 
integer mnth equal to a number from 0 to 12. The value 0 represents the "Month 0" file, with the 
values 1 through 12 representing January through December, respectively. All that's left now is a call 
to open_month() to read in and process the data for the new month selected. 

Function open_month() 

Since we're now opening a new file, we set the flag saved to TRUE. This flag will remain TRUE until 
we modify the data somehow. Next we initialize some variables, then construct the filename for the 
month we'll be opening. 

After opening the file, if we find that the transaction count is 0 (by reading the first two bytes from 
the file), we ask the user if he'd like to start a new month. We have to do this because if the user has 
transactions entered into his .AUT file (automatic transactions), they will be added to this month's 
file automatically when it's opened. This gives the user a chance to change his mind before the 
transactions are entered. 

If the user chooses to open the file, we call load_auto() to load any automatic transactions. If the 
user chooses not to open the file, we set everything back the way it was and exit the function. 

Assuming we've opened the file, the flag dojt will be TRUE, so we clear the window, set the loaded 
flag to TRUE, set up some strings for the display, and store the current month into month. Using a 
while loop, we read in all the checks from the file, keeping a count on the number of deposits and 
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the number of checks as we do. Finally, we initialize some strings and variables, copy the account 
name and the string Edit Mode" into the window's title bar, close the file, and vamoose. 


Summing It Up 

The remaining functions presented in this chapter, though they play important roles in the workings 
of MicroCheck ST, need little discussion. Most of the programming theory used in them has already 
been covered, so I'll give you only a quick run down on what they do: 


load_auto() 

save_check() 

read_check() 

clear_window() 

get_month() 


Loads any automatic transactions that may be in the user's .AUT 
file. 

Saves the data for a check to disk. 

Reads the data for a check from the disk. 

Blanks out the program's window with a white rectangle. 

Brings up the month-selection dialog box and retrieves the 
user's choice. 


get_new_date() 


chk_date() 


updte_buttons() 


Allows the user to change the program's displayed date via a 
dialog box. 

Verifies that the date dialog box in get_new_date() was filled in 
corrected by the user. 

Places new data in the information boxes on the bottom of the 
screen. 


And Now, the Big Finish 

At this point, you should understand how a large-scale program like MicroCheck ST works. The 
remaining source code (and there's a lot of it!) can provide little new material for our discussions. 

The mechanics of putting together a GEM application have been covered well. What remains is fairly 
straight C code that you should be able to figure out for yourself. 

The entire MicroCheck ST program, including complete source code, compiled program, and full 
documentation, can be found on this book's disk version, in the MICROCHK folder. And remember: 
MicroCheck ST is not only an excellent vehicle for a GEM programming tutorial; it's also a handy 
program to use. You'll never have to balance your checkbook by hand again! How often can you get a 
commercial-quality program and a 400-page book for a measly $30? 

I hate long goodbyes, so I'll make this quick. 

I hope that our many C experiments have taught you what you need to know to design and program 
your own full-GEM application programs. I've said it before, and I'll say it again: the only way to learn 
programming is to program. Practice what you've learned. The more time you spend with C, the 
more of a friend it will become. 

See ya. 
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Program Listing #1 

open_acct ( file ) 
char *file; 

{ 

int x, len; 

char zip[10], buf[25]; 


} 


if ( ( acctfile = fopen ( file, "br" )) == 0 ) 

form alert ( 1, "[1][Can't open the file][CONTINUE]" ); 

else { 

fread ( chkname, 1, 26, acctfile ); 

fread ( chkstreet, 1, 26, acctfile ); 

fread ( chkcity, 1, 16, acctfile ); 

fread ( buf, 1, 10, acctfile); 

strcpy ( &chkcity[strlen(chkcity)], ", " ); 

fread ( Schkcity[strlen(chkcity)], 1, 3, acctfile ); 

strcpy ( Schkcity[strlen(chkcity)] , " " ); 

fread ( zip, 1, 10, acctfile ); 

len = strlen ( chkcity ); 

if ( strlen ( zip ) > 5 ) { 

strncpy ( Schkcity[len], zip, 5 ); 
chkcity[len+5] = 0; 

strcpy ( Schkcity[strlen(chkcity)], ); 

strcpy ( Schkcity[strlen(chkcity)], &zip[5] ); 


} 

else 

strcpy ( Schkcity[strlen(chkcity)], zip ); 
fread ( Sbalance, 4, 1, acctfile ); 
if ( fclose ( acctfile ) != 0 ) 

form alert ( 1, "[l][File close error!] [OKAY] ") ; 
check addr [CHKNAME] .ob spec = chkname; 
check addr [CHKSTREE] .ob spec = chkstreet; 
check addr [CHKCITY] .ob spec = chkcity; 
do_new_mnth (); 
if ( loaded ) 

set_menu_entries (); 
else 

balance = 0; 


} 


do_new_mnth () 

{ 

int choice; 

cancdial_addr[CANCSTRG].ob spec = newm; 
choice = get_month (); 
if ( choice == CANCOK ) { 

if ( !saved ) 

save month ( monthfile ) ; 
open new month (); 

} 


save month ( file ) 
char *file; 

{ 

char newmfile[64] ; 
int x; 
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strcpy ( newmfile, file ); 

strcpy ( &newmfile[strlen(newmfile)-3], "BAK" ); 

Fdelete ( newmfile ); 

if ( Frename ( 0, file, newmfile ) == FAILED ) 

form alert ( 1, "[1][Error creating .BAK file!][OK]" 

if ( ( mfile = fopen ( file, "bw" )) == 0 ) { 

form alert ( 1, "[1][Disk Error!|Cannot save \ 
file.] [CONTINUE]" ); 

Frename ( 0, newmfile, file ); 

} 

else { 

fwrite ( Snum trans, 2, 1, mfile ); 
for ( x=0; x<num trans; ++x ) 
save check ( x, mfile ); 
if ( fclose ( mfile ) != 0 ) 

form^alert ( 1, "[1][File close error!] [OKAY]"); 
else 

saved = TRUE; 

if ( ( mfile = fopen ( filename, "br+" )) == NULL ) 

form^alert ( 1, "[1][Error opening .MCK file!|\ 

Cannot update balance.][OK]" ); 
else { 

fseek ( mfile, 91L, FROM_BEG ); 
fwrite ( Sbalance, 4, 1, mfile ); 
if ( fclose ( mfile ) != 0 ) 

form alert ( 1, "[1][File close error!][OK]") ; 

} 


} 


} 


open new^month () 

{ 

int mnth, x; 

for ( x=JAN; x<=MZERO; ++x ) 

if ( cancdial addr[x].ob_state == SELECTED ) 
if ( x == MZERO ) 
mnth = 0; 
else 

mnth = x-JAN+1; 

sprintf ( cancmnth, "%d", mnth ); 
open month ( acct name, cancmnth ); 

} 


open month ( file, mnth ) 
char *file, *mnth; 

{ 

int x, len, button, do it, trans_cnt, old dep_cnt, 
old_chk_cnt; 

char a[20], new mfile[64]; 

saved = TRUE; 
old_dep_cnt = num deps; 
old_chk cnt = num_chks; 
num_chks = num_jdeps = 0; 
strcpy ( new mfile, filename ); 

strcpy ( Snew^mfile[strlen(new_mfile)-4], mnth ) ; 
strcpy ( &new_mfile[strlen(new_mfile)], ".DAT" ); 
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if ( ( mfile = fopen ( new^mfile, "br" )) == 0 ) 

form alert ( 1, "[1][Can't open the file][CONTINUE]" ); 

else { 

do_it = TRUE; 

fread ( &trans_cnt, 2, 1, mfile ); 
if ( trans_cnt == 0 ) { 

button = form alert ( 1, "[2][The data file for|this \ 
month is empty.|Do you want to start|a new month?][YES|NO]" ); 
if ( button == YES ) { 

num_trans = load_auto (); 

} 

else { 

do_it = FALSE; 
num_chks = old_chk_cnt; 
num deps = old dep_cnt; 

} 

} 

else 

num trans = trans_cnt; 
if ( do_it ) { 

clear window (); 
loaded = TRUE; 

if ( balance < 0 && balance > (-100) ) 

sprintf ( bal_but, "$-%ld.%021d" , 

balance/100,labs(balance%100) ); 

else 

sprintf ( bal_but, "$%ld.%021d" , 

balance/100, labs(balance%100) ); 

strcpy ( monthfile, new mfile ); 
strcpy ( acct_name, file ); 
month = atoi ( mnth ); 
x = 0 ; 

while ( x < trans_cnt ) { 

read_check ( x, mfile ); 

if ( strcmp ( checks[x].number, "9999" ) == MATCH ) 
num deps += 1; 
else 

num chks L= 1; 

++x; 

} 

if ( x > 0 ) { 

strcpy ( cur_chk num, checks[x-1].number ); 
curchknum = atoi ( cur_chk num ); 
if ( strcmp ( cur_chk num, "9999" ) != MATCH ) { 

curchknum += 1; 

sprintf ( a, "%d", curchknum ); 

len = strlen ( a ); 

strcpy ( &cur_chk_num[4-len], a ); 

} 

} 

cur_top = edit_top = 0; 
cur_count = num trans; 
cur_chk_strc = checks; 
strcpy ( windname, acct name ) ; 

strcpy ( Swindname[strlen(windname)], Edit mode" ); 
wind_set ( w_h2, WF NAME, windname, 0, 0 ); 
full draw = TRUE; 
if ( fclose ( mfile ) != 0 ) 

form alert ( 1, "[l][File close error!][OKAY] ") ; 

} 

} 
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} 


load_auto () 

{ 

char autoname[64]; 
FILE *autofile; 
int x, count; 


count = 0; 

strcpy ( autoname, filename ); 

strcpy ( Sautoname[strlen(autoname)-4], ".AUT" ); 
if ( ( autofile = fopen ( autoname, "br" )) != NULL ) { 

fread ( Scount, 2, 1, autofile ); 
x = 0 ; 

while ( x < count ) { 

read_check ( x, autofile ); 

if ( strcmp ( checks[x].number, "9999" ) == MATCH ) 
num^deps += 1; 

balance += checks[x].amount; 

} 

else { 

num_chks += 1; 

balance -= checks[x].amount; 


++x; 


} 

saved = FALSE; 


if ( 

fclose ( 

autofile 

) == FAILED ) 

form alert 

( 1, "[1] 

[Error closing 

[CONTINUE]" 
} 

return ( 

} 

) ; 



count ); 



save check 
int i; 

FILE *f ; 

{ 

fwrite ( 

( i, f ) 



checks[i 

].number. 

1, 4, f ); 

fwrite ( 

checks[i 

].payee. 

1, 30, f ) ; 

fwrite ( 

checks[i 

].memo, 1 

, 30, f ) ; 

fwrite ( 

checks[i 

].date, 1 

, 8 , f ) ; 

fwrite ( 

Schecks[ 

i].amount 

, 4, 1, f ); 

fwrite ( 

checks[i 

].cancel, 

1, 1, f ); 

fwrite ( 

} 

"THIS SPACE FOR POSSIBLE FUTURE 

read check 
int i; 

FILE f; 

{ 

fread ( 

( i, f ) 



checks[i] 

.number. 

1, 4, f ); 

fread ( 

checks[i] 

.payee, 1 

, 30, f ); 

fread ( 

checks[i] 

.memo, 1, 

30, f ); 

fread ( 

checks[i] 

.date, 1, 

8 , f ) ; 

fread ( 

Schecks[i 

].amount. 

4, 1, f ); 

fread ( 

checks[i] 

.cancel, 

1, 1, f ); 

fread ( 

future use, 1, 40, 

f ) ; 
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} 


clear window () 

{ 

GRECT r; 


wind get ( w h2, WF WORKXYWH, &r.g x, &r.g y, &r.g w, &r.g h) ; 
draw rec ( r, 2, 8, WHITE ); 


get_month () 

{ 

int choice; 

int dial_x, dial y, dial w, dial h; 
clear_cancdial (); 

form^center(cancdial addr,&dial_x,&dial_y,&dial w,Sdial^h); 
form dial(FMD_START,0,0,10,10,dial x,dial_y,dial w,dial h) ; 
objc^draw(cancdial addr,0,8,dial x,dial_y,dial w,dial_h); 

choice = form do ( cancdial_addr, 0 ); 

cancdial_addr[choice].ob state = SHADOWED; 

form dial(FMD FINISH,0,0,10,10,dial_x,dial y,dial_w,dial h); 
return ( choice ); 


clear^cancdial () 

{ 

int x; 

for ( x=JAN; x<=MZERO; cancdial_addr[x++].ob state = NORMAL); 
if ( month != -1 ) 
if ( month == 0 ) 

cancdial addr[MZERO].ob state = SELECTED; 
else 

cancdial addr[month+JAN-1].ob state = SELECTED; 
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get_new_date () 

{ 

int choice, okay; 

int dial_x, dial y, dial w, dial_h; 

string = get tedinfo str ( newdate addr, NWDATE ); 
string[0] = 0; 

form^center(newdate addr,&dial_x,&dial y,Sdial w,&dial_h); 
form_dial(FMD_START,0,0,10,10,dial x,dial_y,dial w,dial_h); 
objc^draw(newdate addr,0,8,dial_x,dial y,dial_w,dial h) ; 

okay = FALSE; 

do { 

choice = form do ( newdate addr, NWDATE ); 
newdate addr[choice].ob state = SHADOWED; 
switch ( choice ) { 

case DATEOK: 

okay = chk_date (); 
if ( lokay ) 

objc_draw ( newdate_addr, 0, 8, 

dial x, dial^y, dial_w, dial_h ); 

else { 

strcpy ( cur_date, string ); 
format_date ( date_but, cur_date ); 
updte_buttons (); 

} 

break; 

case DATECANC: 

string = get tedinfo str ( newdate addr, NWDATE ); 
string[0] = '@' ; 

} 

} 

while ( okay == FALSE && choice != DATECANC ); 

form dial(FMD_FINISH,0,0,10,10,dial_x,dial y,dial_w,dial h); 
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chk_date () 

{ 

int mnth, day, year, okay; 
char m[3], d[3], y[3] ; 

string = get tedinfo str ( newdate addr, NWDATE ); 
if ( strlen ( string ) == 6 ) { 

strncpy ( m, string, 2 ); 
m[2] = 0; 

strncpy ( d, &string[2], 2 ); 
d[2 ] = 0; 

strncpy ( y, &string[4], 2 ); 
mnth = atoi ( m ); 
day = atoi ( d ); 
year = atoi ( y ); 

if ( mnth < 0 | mnth >12 | day < 1 | day > 31 
I year < 0 | year > 99 ) { 
okay = FALSE; 

} 

else 

okay = TRUE; 

} 

else 

okay = FALSE; 
if ( !okay ) { 

form_alert ( 1, "[1][Not a valid date!][CONTINUE]" ); 
string[0] = 0; 

} 

return ( okay ); 


updte_buttons () 

{ 

if ( !full ) { 

set_buttons (); 

center_butstring ( bal_but, 35, 194 ); 
center_butstring ( trans_but, 131, 194 ); 
center_butstring ( check but, 227, 194 ); 
center_butstring ( dep_but, 323, 194 ) ; 
center_butstring ( mnth but, 419, 194 ); 
center_butstring ( date_but, 515, 194 ) ; 

} 

} 
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APPENDIX A - ST-CHECK 

typing in a basic program listing can be a frustrating and time-consuming task. Just one mistyped 
character will frequently render a program completely unusable. So to ensure that your program will 
run correctly, the entire listing must be checked character by character against the original. This can 
take many hours. To make matters worse, you can't trust your own eyes. Do you know how easy it is 
to overlook an O where a 0 is supposed to be? 

Typing checkers like ST-Check take over the arduous task of proofreading your program files. Using 
this program can cut down your debugging time by a huge factor. When the checker's output 
matches that published with the listing, you can be sure your typing is accurate. 

Introspection 

When you run ST-Check against itself, you will get one of several results. The program may just give 
up and crash. In that case, go through the listing character by character until you find your typing 
error. 

A second possibility is that the program will run okay, but will create all bad checksum data. This may 
indicate an error between lines 80 and 420.Find the typo and correct it. 

The last possibility is that the checksum data will have only a few bad values. In this case, use the 
normal method detailed below to locate your errors. 

Warning: Until you get your checksum data for ST-Check to match the data following the listing, you 
can't trust it to proofread other programs. 

Using ST-Check 

When you finish typing an ST BASIC program listing from a chapter, save a copy to your disk, and 
then run ST-Check. The program will first ask for a filename. Type in the name for the program you 
wished checked (the one you just saved to disk), and press Return. You'll then be asked for a "bug" 
name. Enter a filename for the checksum file (this can be any name not already on the disk), followed 
by Return. 

ST-Check will now proofread the program. When the checking process is complete, you'll have a file 
on your disk (saved under your bug name) which contains the checksum data for the program 
checked. 

Check the last value of each line. If it matches the value in the published checksum data, go on to the 
next. If it doesn't match, you've got a typo. 

To find the error, look at the line number of the data statement in which the bad value occurred. This 
number is equivalent to the first program line the data evaluates. Let's call this "Line X." Count the 
entries in the data line until you get to the bad value. We'll call this count "Y." Now look at the 
program you typed in. Starting with and including Line X, count down Y lines. The line you end up on 
will be the one containing the typo. 

Correct the error, and then rerun ST-Check. When you get all the checksum data to match that 
published at the end of the chapter, your new program is ready to run. 

Passing the Buck 

Okay, friends. Here's where the truth comes to the fore. I can take only minimal credit for ST-Check, 
as it's virtually a direct translation from D:CHECK2 (A.N.A.L.O.G. Issue #16) by Istvan Mohos and Tom 
Hudson. All accolades should be directed to those two fine gentlemen. I'm sure they'll divvy it up 
fairly, and perhaps pass a small share on to me. Thanks, guys! 
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You may now type in the ST BASIC program listings presented in this book, secure in the knowledge 
that the searching eye of ST-Check is primed and ready. 

Program Listing #1 

10 'ST CHECK typing validator by Clayton Walnum 

20 'based on a program by Istvan Mohos and Tom Hudson 

30 if peek(systab)=1 then cl=17 else cl=32 

40 fullw 2:clearw 2:gotoxy cl,0:? "ST CHECK":ex=0:sp=0: x=0 
50 input "Enter filename: ",f$:input "Enter BUG name: ",fl$ 

60 on error goto 590:open "0",#1,f1 $:open "I",#2,f$:close #2 
70 open "I",#2,f$:on x goto 140,220 

80 color 2:?:? "Counting lines":linecount=0:color 1 
90 on error goto 570 

100 line input#2, i$ :linecount=linecount+l 
110 ? ".:goto 100 

120 close #2:q=int (linecount/10) :dim c(linecount),r(q) 

130 x=l:goto 70 

140 range=0:lyne=0:color 2:?:?:? "Filling array":color 1 

150 ? ".";:count=0 

160 line input#2, ^L$ : count=count+l 

170 lyne=val (i$) :r(range)=lyne:range=range+l 

180 on error goto 580 

190 line input#2, _i$ :count=count+l:if count=10 then 150 

200 goto 190 

210 close #2:x=2:goto 70 

220 color 2:?:?:? "Calculating checksums":color 1 

240 for _i=l to linecount:checksum=0:line input #2,i$:l=len (i$) 

245 if mid$(i$,l,l)=" " then 1=1-1:goto 245 
250 for z — 1 to 1:number=asc(mid$( i$ ,z,1)) 

260 if number=asc(" ") and ex=0 and sp=l then goto 320 

270 if numberOasc (" ") then sp=0 else sp=l 

280 if number<>34 then 300 

290 if ex=l then ex=0 else ex=l 

300 if ex=0 and number>=asc("a") and number<=asc("z") then number=number-32 
310 product=x*number:checksum=checksum+product:x=x+l:if x=4 then x=l 
320 next z:? "."; 

330 checksum=checksum-1000*int(checksum/1000) :c( jl) =checksum: x=2 :next i 
340 close #2:lyne=r(0):item=0 

350 color 2:?:?:? "Creating BUG file":color 1 

360 count=10:total=0:if linecount<10 then count=linecount 

370 i 1 $=str$ (lyne) : i$=i$ + " data " 

380 for i=l to count:datum=c(10*item+i) 

390 _i$=i$+str$(datum):i$=i$+",":total=total+datum:next i 

400 _i$=i$ + str$ (total):print #l,i$:? 

410 item=item+l:linecount=linecount-10:if linecountkl then 430 

420 lyne=r(item):goto 360 

430 close #l:clearw 2:?:gotoxy 0,1 

440 ? "To check BUG data against the checksum data found in the magazine," 

450 ? "return to the GEM desktop and double click your BUG file. You may" 

460 ? "then SHOW the data on your screen or PRINT the data to your printer.":? 

470 ? "The line number of each data statement coincides with the first line" 

480 ? "of the user program the data statement evaluates. Numbers within" 

490 ? "each data statement represent consecutive lines of the user program." 

500 ? "The last number is the total.":? 

510 ? "Check the last number of each statement against the version in the" 

520 ? "magazine. Only when there's a discrepancy need you check each number" 

530 ? "in the data statement.":? 

540 ? "Take note of the lines containing typos, then make corrections. When" 

550 ? "all corrections have been made, rerun this program to double check." 

560 ? "Press <RETURN>":input i$:close #l:close #2:end 

570 if err=62 then resume 120 
580 if err=62 then resume 210 

590 if err=53 then ? chr$(7);"FILE NOT FOUND!":close:resume 50 
600 ? "ERROR #";err;" at LINE ";erl:end 
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Program Listing #2 

ST-Check Checksum Data 


10 data 447,129,203,518,661,160,942,482,640,556,4738 
110 data 25,905,797,52,79,349,852,644,9,482,4114 
210 data 883,479,834,822,42,498,255,165,826,410,5214 
310 data 337,1,166,578,136,801,898,937,271,769,4894 
410 data 363,99,155,889,243,764,168,192,906,156,3935 
510 data 757,251,146,509,146,916,539,541,733,845,5383 
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Taylor Ridge Book Order Form 

To order products from Taylor Ridge Books, remove or copy this page, complete the order form and 
mail to: 


Taylor Ridge Books 
P.O. Box 78 
Manchester, CT 06045 
(203) 643-9673 


Item 

C-manship Book Only 
C-manship Disk Only 
C-manship Book & Disk 


Qty. Price Ea. Total 
$19.95 
10.00 
29.95 


Beyond the Nintendo Masters 9.95 

$2.00 Fourth Class 
3.50 UPS 
4.00 First Class 
6.00 C.O.D. 


SUBTOTAL 
SALES TAX 

CT residents add 8% tax 


Add $1.50 for each additional book. SHIPPING CHARGE 

A C-manship disk pack when ordered with a 
book requires no additional S&H, but a disk 

pack without the book is $1.50 S&H ea. TOTAL AMOUNT 


PLEASE PRINT 


Name: 

Address: 
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